From Idea to Architecture

Start with a problem, not a technology

The biggest mistake people make when building with AI is jumping straight into code. They ask 'build me a Next.js app' instead of 'I need a website that sells online courses in two languages.' The technology is a means to an end. When you describe the problem clearly, AI can propose a much better solution than when you dictate the stack.

This course documents how PraktickAI — the very site you are reading this on — was built entirely with AI agents. Every line of code, every deployment script, every database migration was written by Claude Code. A human made the architecture decisions and validated the output. AI did the rest.

How to describe your project to AI

Think of your first conversation with AI as a project brief. You are the client, AI is the consultant. Describe what you need, who it is for, and what constraints you have. The more specific you are about the problem, the better the architecture proposal will be.

I need a website for my AI training and consulting business.

Requirements:
- Bilingual (Czech + English), with easy addition of more languages later
- Sell online courses with payment gateway
- Blog with SEO-optimized pages
- Social login (Google, LinkedIn)
- Admin panel for managing content
- Must be cheap to host (under EUR 10/month total)
- Must be fast to build (one developer + AI)

Constraints:
- I know Python and some JavaScript
- I want to deploy to my own infrastructure, not be locked into a platform
- Content should be easy to update without redeploying

Notice there is no mention of Next.js, Django, or any specific technology. You describe the problem. AI proposes the solution. This is a critical mindset shift: you are the architect, AI is the builder.

Let AI propose the architecture

When you give AI a clear problem description, it can propose a surprisingly good architecture. For PraktickAI, Claude suggested a split frontend/backend approach: Next.js for the frontend (great SEO, built-in i18n, Vercel hosting), and Django for the backend (mature ORM, admin panel, Python ecosystem). This was the right call.

claude "Based on my requirements, propose an architecture.
       Include: tech stack, hosting strategy, database,
       CI/CD approach, and cost estimate.
       Explain WHY you chose each technology."

The key phrase is 'explain WHY.' Without it, AI just lists technologies. With it, you get reasoning you can evaluate. For PraktickAI, the reasoning was: Next.js because Vercel offers free hosting for frontends and has excellent i18n support. Django because its ORM and admin panel save weeks of work, and Django Ninja provides type-safe APIs with automatic OpenAPI docs.

The CLAUDE.md file: your project's brain

Once you have an architecture, the single most important file you will create is CLAUDE.md. This is a markdown file at the root of your project that tells AI agents everything they need to know: how to run the project, how tests work, what the API looks like, deployment details, and hard-won lessons (gotchas).

Think of CLAUDE.md as institutional memory. Every time AI discovers something the hard way — a Kubernetes gotcha, a quirk of the payment gateway, an important environment variable — it goes into CLAUDE.md. Future AI sessions read this file first and avoid repeating mistakes.

# MyProject Backend

Django + Django Ninja REST API.

## Quick Start

    docker compose up -d db
    uv run python manage.py migrate
    uv run python manage.py runserver 0.0.0.0:8008
    uv run pytest

## Architecture Notes

- Frontend proxies /api/* to backend via vercel.json rewrites
- Social auth: code must be injected into request.POST BEFORE
  calling load_strategy() — social_core caches request data at init

## K8s Gotchas (learned the hard way)

- DATABASE_URL must be URL-encoded — passwords with / break django-environ
- SECURE_SSL_REDIRECT must be off until TLS is set up
- Health probes need Host: localhost header

The README as a contract

Beyond CLAUDE.md, your README serves as a contract between you and AI. Write what you want the project to become, not just what it is. Include your goals, your timeline, your non-negotiables. AI reads this and aligns its work accordingly.

For PraktickAI, the README includes the business context (AI training consultancy), the target audience (technical teams), pricing strategy, and deployment targets. When AI creates a new feature, it has all this context and makes better decisions — like keeping the UI professional rather than playful, or prioritizing Czech content over English.

The real PraktickAI stack (and what it costs)

• Frontend: Next.js (App Router), TypeScript, Tailwind CSS — hosted on Vercel (free tier)
• Backend: Django + Django Ninja REST API — hosted on k3s (Kubernetes) on Hetzner VPS
• Database: PostgreSQL — on the same Hetzner VPS
• AI tools: Claude Code (primary), GitHub Copilot (secondary)
• CI/CD: GitHub Actions — lint, type-check, test, deploy on every push
• Total monthly cost: EUR 3.49 (just the Hetzner VPS)

That is not a typo. A full production web application with bilingual support, payment processing, social authentication, and automated deployments runs for EUR 3.49 per month. The frontend is free (Vercel), the database runs on the same VPS as the backend, and GitHub Actions are free for public repos.