Lesson 2.4 · 50 minTechnical plan

What you will have

The student has docs/architecture.md with a diagram, a data model and a roadmap, a CLAUDE.md that points at all four planning documents, and can explain aloud how a quote request travels through the system.

Video

The video for this lesson is not recorded yet.

Prompts used in this lesson

Part 5 — Demonstration: writing the architecture document

Purpose: Write the technical plan so that I, a beginner, can explain the
system aloud and later sessions build towards the same structure.

Context: Read @docs/brief.md, @docs/content.md and @docs/design.md.
Stack: Next.js (App Router) with TypeScript and Tailwind CSS; Supabase for the
Postgres database and Auth; Vercel for hosting; Resend for email; Telegram Bot
API for owner notifications; Cloudflare Turnstile for spam protection. Later
sections add analytics, ad tracking and the Claude API.
Routes: / landing page, /thank-you, /privacy, /terms, /lp/<campaign> campaign
pages, /admin CRM (with /admin/login, /admin/leads, /admin/leads/<id>,
/admin/pipeline, /admin/today), /api/leads lead endpoint.
Tables: leads (id, created_at, name, email, phone, message, status, utm_source,
utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid, referrer,
landing_page, ab_variant, score, score_reason), lead_notes, lead_tasks,
lead_status_history. Statuses: new, contacted, qualified, won, lost.
Migrations live in supabase/migrations/.
Build order: website, then backend, CRM, analytics, advertising, operations.

Done looks like: a file docs/architecture.md with
1. Overview: one paragraph a non-programmer can read.
2. Diagram: a Mermaid flowchart of browser, server, database and each
   third-party service, with labelled arrows; under it, the journey of one
   quote request as numbered steps.
3. Parts and services: a table of each part, its job here, and whether it
   runs in the browser, on the server, or outside.
4. Costs: a table with columns service, plan, cost, limits, commercial use
   allowed, pricing page, checked on. Fill in only the service names.
5. Routes: each address and what it is for.
6. Data model: each table, what one row means, how the tables relate; the
   leads columns in groups with one line on each group.
7. Secrets: keys live only in .env.local and the hosting provider's
   environment settings, never in code or chat. No values.
8. Roadmap: the build order as milestones, each with what will visibly work.
9. Decisions: anything that differs from the stack above.

Constraints: This is a plan only. Do not create code, install anything or
create accounts. Do not state prices or plan limits. Explain every technical
term the first time it appears. Keep it under about three pages.

Do along

Work on your own project. Pause the video where a step says so.

1. Start with your three committed documents. Open Claude Code in the project.
2. Pause when the prompt appears in Part 5. Use it. Change the Stack line only if you substitute a tool. Keep the routes and tables as given so your project matches later lessons. If your conversion action is not a quote request, add a line saying so.
3. Read docs/architecture.md and do the four checks from Part 5; have Claude explain and simplify anything unclear.
4. Fill in the cost table yourself from each pricing page, with today's date.
5. Add your own dates to the roadmap.
6. Pause when the "Project documents" section appears in Part 6. Add it to CLAUDE.md, with your own summary.
7. Run the fresh-session test from Part 6.
8. Explain the diagram aloud to a person or a recorder. Then ask Claude: "Ask me three questions, one at a time, about the diagram and data model in docs/architecture.md, and correct my answers in plain words."
9. Commit, tag and push.

Check your work

1. docs/architecture.md has a diagram, numbered steps and a data model. → All four kinds of part, four tables and five statuses appear.
2. The cost table. → Filled in by you, with a date; no figure from Claude.
3. git status before committing. → Only docs/architecture.md and CLAUDE.md changed.
4. Explain the journey of one quote request aloud without looking. → You name each part and what it does.
5. After /clear, the summary prompt. → Audience, action, stack, tables and first build step are correct.
6. After pushing: git tag lists lesson-2.4, and on GitHub the diagram shows as a picture.

Common problems

• Claude started creating a project or installing packages. → "Plan only" was lost. → Press Esc to stop it, check git status, undo unwanted files as in lesson 0.4, and repeat the prompt.
• The cost table has prices in it. → Claude filled it from memory. → Say: "Remove every price and limit; I will fill the table in myself."
• The diagram is only text. → Your editor has no Mermaid preview. → View it on GitHub. If it fails there too, tell Claude it does not render and ask it to fix the syntax.
• The fresh session's summary is vague or wrong. → CLAUDE.md does not mention the documents, or a document is wrong. → Run /context and check that CLAUDE.md is listed under memory files; then correct the document holding the wrong fact.

Homework

About 30 minutes, after the lesson. Nothing here is needed to start section 3. Do not change the routes, tables or statuses. If a file changes, commit without a tag.

1. A second journey (~10 min). In your notes, write as numbered steps what happens when you, the owner, open the admin area and move a lead from "new" to "contacted". Name the browser, the server, the database and each table touched. Then paste your steps to Claude and ask: "Check these steps against docs/architecture.md and correct me in plain words. Do not change any file." Done when: Claude finds no part in the wrong place, or you have corrected your steps.
2. What it costs to run (~10 min). From the cost table you filled in, add up the fixed cost per month and per year at the plans you chose, leaving out advertising. Write both totals and today's date in one line under the table. Do not buy or upgrade anything. Done when: the line is there, with both totals and the date.
3. Block the time (~10 min). Take the date you gave the first roadmap milestone, the live website. Add up the lesson times of section 3 from the course programme, and put working sessions in your calendar that cover them before that date. Done when: the sessions are in your calendar; if they do not fit, the roadmap date is moved.

Save your work

git add -A
git commit -m "Lesson 2.4: technical plan and project documents"
git tag lesson-2.4
git push
git push --tags