41  41. Putting It Together: Architecting a Web App with AI

This page pulls the whole “How the Web Works” part together. You will take a product idea, break it into the building blocks from the previous pages, draw the architecture, and use Claude Code as a design partner - before writing a single line of code.

41.1 The idea: a club event sign-up app

Student clubs run events, and sign-ups are messy: spreadsheets, group chats, no-shows, nobody knows who is on the waitlist. The idea, “ClubHub”:

• Members browse upcoming events, sign up with one click, cancel, join a waitlist when an event is full, and get a reminder email the day before.
• Officers create and edit events, set a capacity, see who signed up, and export the list.
• Some events (a trip, a formal) cost money, so members pay online.
• Nice to have: an AI helper that drafts an event description from a few bullet points.

Two kinds of users with different permissions, data that must be stored and shared, logins, money and an AI feature: a typical small business app.

41.2 From features to building blocks

Need	Building block	One possible choice	Covered in
Screens members and officers see	Front end	Next.js (React)	Frameworks, HTML/CSS/JS
Rules: capacity, waitlist, who may edit	Back end	Next.js server code	The server
Members, events, sign-ups	Database	PostgreSQL (via Supabase)	The server
Log in with a school Google account	Authentication (OAuth)	Supabase Auth with Google	APIs and keys
Pay for paid events	Payments	Stripe	APIs and keys
Reminder emails	Email service	Resend (or similar)	APIs and keys
Draft event descriptions	AI	Claude API, called from the back end	APIs and keys
Put it online	Hosting	Vercel (or Netlify) + Supabase	Hosting
A memorable address	Domain (optional)	Free *.vercel.app address at first	DNS

These are reasonable, popular choices - not the only ones. Popular choices have a practical advantage: AI tools know them well.

41.3 The architecture

                    Members and officers (browsers)
                                 |
                                 |  HTTPS
                                 v
 +-------------------------------------------------------------+
 |  Hosting: Vercel (or Netlify)                               |
 |                                                             |
 |  Next.js app                                                |
 |   - front end: event list, sign-up button, officer pages    |
 |   - back end: sign-up rules, waitlist, officer-only actions |
 |     (the only place that holds secret keys)                 |
 +-------------------------------------------------------------+
        |                 |                |              |
        v                 v                v              v
 +---------------+  +------------+  +------------+  +-------------+
 | Supabase      |  | Stripe     |  | Resend     |  | Claude API  |
 | - PostgreSQL  |  | payments   |  | email      |  | AI drafts   |
 | - Auth (with  |  +------------+  +------------+  +-------------+
 |   Google)     |
 +---------------+

And the core data, as tables:

Table	Main columns
members	id, name, email, role (member or officer)
events	id, title, date, location, capacity, price
signups	member_id, event_id, status (confirmed or waitlist), created_at

The full-stack tutorial in this book builds an app with a very similar shape. Its diagram is below; it uses OpenAI’s API where we use the Claude API, and runs some back-end code as Supabase Edge Functions:

The architecture of the app built in this book’s full-stack tutorial: a Next.js web app in the browser and on Vercel, Supabase (authentication, PostgreSQL database, storage, edge functions), and third-party services (Google OAuth, OpenAI API, Stripe).

41.4 Start small: the MVP

An MVP (minimum viable product) is the smallest version that real users can try. For ClubHub, version 1 could be: log in with Google, see upcoming events, sign up and cancel, and let officers create events. The waitlist, payments, emails and AI drafts come later, one at a time.

Starting small means less to build and debug, feedback from real members sooner, fewer accounts, keys and bills at first - and an AI makes far fewer mistakes on small, well-defined steps than on “build the whole app”.

41.5 Designing with Claude Code

As of Oct 6, 2026 · Official docs: Best practices for Claude Code · Permission modes (plan mode) · How Claude remembers your project

An AI coding agent is a fast, well-read partner for architecture - if you lead the conversation:

1. Describe the problem, not the technology. Who are the users, what must they be able to do, and what are your constraints: budget, deadline, team skills, “members log in with school Google accounts”.
2. Discuss in plan mode. In plan mode, Claude Code reads files and proposes a plan but doesn’t edit your files. Press Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan (details in Permissions, Modes, and Safety).
3. Ask for options and trade-offs, not just one answer: two or three possible architectures compared on cost, complexity, free-plan limits and risks.
4. Ask it to explain every piece in plain English - what it does, why it is needed, what happens if it fails - until you could explain the diagram to someone else.
5. Let it interview you, then write a spec. Claude Code’s best-practices guide suggests asking Claude to interview you about the feature and then write the result to a file such as SPEC.md (writing a file means leaving plan mode). Good specs say what is out of scope and how you will check that it works. Then start a fresh session to build from the spec.
6. Record lasting decisions in CLAUDE.md, the file Claude Code reads at the start of every session: the stack, the commands to run, required environment variables, conventions (see CLAUDE.md and Memory).
7. Verify claims. Prices, free plans and library versions change faster than AI training data. Check the official pricing and documentation pages, or ask Claude to look up the current docs and show you its sources.
8. Watch costs and secrets. List every paid service and its limits, keep keys in .env files and host settings only, and never paste a real key into the chat.

A first prompt might look like this:

I'm planning a web app for student clubs (feature list below).
Constraints: three business students, beginner coders, $0 budget,
must be live in 6 weeks, members log in with school Google accounts.

Don't write any code yet.
1. Propose 2-3 possible architectures (front end, back end, database,
   login, hosting, email, payments) and compare them in a table:
   monthly cost at 100 and at 5,000 members, complexity, free-plan
   limits, and risks.
2. Recommend one and explain each piece in plain English.
3. Define a minimal first version (MVP) we can build in two weeks.
4. List the accounts, API keys and environment variables we will need.

For the spec, the best-practices guide offers this interview prompt (AskUserQuestion is the built-in tool Claude uses to ask you multiple-choice questions):

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

41.6 Checklist: questions to answer before coding

Users and features

• Who are the users, and what roles do they have (member, officer, admin)?
• What are the 3-5 must-have features of the MVP? What is explicitly out of scope?

Data and permissions

• What data will you store (tables and columns)? What is personal or sensitive?
• Who may see and change each kind of data? Where is that enforced (it must be the back end or database rules, not only the front end)?

Architecture and services

• Which front end, back end, database and login approach - and why?
• Which third-party services will you use? Which cost money, what are their free-plan limits, and what happens when you exceed them?

Secrets and costs

• Which keys exist, where are they stored in development and in production, and who has access? Are spending limits set?

Operations

• Where will development, previews and production run, and how do you deploy (push to GitHub)?
• How will you check that it works: a manual test checklist, automated tests, Claude testing it in a browser?
• What if a free plan pauses or sleeps before demo day? Who owns each account?

To see an app of this shape built step by step, work through the full-stack tutorial.

Practice Questions

Easy

Question 1 · Short answer

What is an MVP, and why start with one?

Suggested answer

A minimum viable product: the smallest version of the product that real users can try. Starting with one means less to build and debug, earlier feedback from users, fewer services, keys and costs at first, and smaller, clearer steps for the AI to get right.

Question 2 · Matching

Match each ClubHub need with the building block that handles it.

Need		Building block
1. Remember who signed up for which event		A. Payment service (Stripe)
2. “Log in with Google”		B. Email service
3. Pay for the ski trip		C. Database
4. Reminder the day before		D. Authentication (OAuth)

Suggested answer

1 → C, 2 → D, 3 → A, 4 → B.

Question 3 · True or false

The best first step with Claude Code is to describe your idea in one sentence and ask it to build the whole app right away.

Suggested answer

False. First clarify requirements and constraints, ask for options and trade-offs, agree on a plan (for example in plan mode), and write a short spec. Then build a small MVP step by step. Jumping straight to code often solves the wrong problem.

Question 4 · Multiple choice

What does Claude Code do in plan mode?

1. It writes and runs code without asking
2. It reads files and proposes a plan, but doesn’t edit your files
3. It only answers questions about Claude’s pricing
4. It deploys your app to production

Suggested answer

b. Plan mode separates thinking from doing: Claude explores and writes a plan, and edits wait until you approve it. It is the opposite of (a), and it has nothing to do with pricing (c) or deployment (d).

Medium

Question 5 · Scenario

Events have a capacity of 30. Where must the “no more than 30 confirmed sign-ups” rule be enforced, and what should happen to the 31st person?

Suggested answer

In the back end (and ideally backed up by database rules), because front-end checks can be bypassed and two people may click at the same moment. When the event is full, the back end saves the 31st sign-up with status waitlist instead of confirmed (or refuses it, if there is no waitlist), and the front end shows the result.

Question 6 · Long answer

Write a prompt asking Claude Code for architecture options for your own app idea, without code. What must a good prompt include?

Suggested answer

A good prompt includes: who the users are and what they need to do; the constraints (budget, deadline, team skills, required logins or data rules); an explicit “don’t write code yet”; a request for 2-3 options compared in a table (cost, complexity, limits, risks); a request to explain each piece in plain English; and a request for an MVP and a list of the accounts, keys and environment variables needed. The sample prompt on this page is a model answer.

Question 7 · Compare

ClubHub has both a SPEC.md and a CLAUDE.md. What belongs in each?

Suggested answer

• SPEC.md: the plan for what to build - features, user roles, screens, data, what is out of scope, and how to check that it works.
• CLAUDE.md: short, lasting facts Claude should know in every session - the chosen stack and architectural decisions, the commands to run and test the app, required environment variables (names, not values), and conventions.

Question 8 · Ordering

Put these steps in a sensible order: (a) build the MVP in small steps, (b) describe users, needs and constraints, (c) write a spec, (d) compare architecture options and pick one, (e) record the key decisions in CLAUDE.md.

Suggested answer

b → d → c → e → a. (Writing CLAUDE.md alongside the spec, or updating it as you build, is also fine - the point is that understanding and planning come before building.)

Question 9 · Scenario

Claude tells you that a hosting service “has a generous free tier with unlimited projects”. What should you do before relying on it?

Suggested answer

Check the service’s official pricing page today (or ask Claude to fetch the current page and quote it). Free plans change often, and the AI’s training data may be out of date - some hosts that once had free plans no longer do. Also note the limits that matter to you: commercial use, sleeping or pausing, usage caps.

Question 10 · Short answer

Name the four main tables (or the three core ones) you would need for ClubHub, and what links a sign-up to a member and an event.

Suggested answer

The core tables are members, events and signups (a fourth, such as payments, can come later). Each row in signups stores a member_id and an event_id, which point to rows in members and events, plus the sign-up’s status (confirmed or waitlist).

Hard

Question 11 · Scenario

Describe how the “AI drafts the event description” feature should work in this architecture: who calls the Claude API, where the key lives, and how you keep the cost under control.

Suggested answer

The officer’s browser sends the bullet points to ClubHub’s back end, which checks that the user is an officer, calls the Claude API with the key from its environment variables (.env.local in development, the host’s settings in production), and returns the draft. The key never reaches the browser. Cost control: only officers can use the feature, limit how often they can, keep the prompt and output short, use a smaller model if it is good enough, and set a monthly spend limit in the Claude Console.

Question 12 · Compare

For a beginner team, compare using Supabase (database and logins as a service) with writing your own Express API and PostgreSQL database on Render. Give one advantage of each.

Suggested answer

• Supabase: much less code to write and secure - logins (including Google), the database and its API are ready-made, with a free plan to start. The trade-off: you must learn its rules (such as Row Level Security) and accept its limits, such as pausing inactive free projects.
• Own Express API on Render: full control and a deeper understanding of how a back end works; nothing hidden. The trade-off: you must build and secure logins, permissions and every endpoint yourself, which is slower and riskier for beginners (and Render’s free databases expire).

For most beginner teams, Supabase (or a similar service) is the safer start.

Question 13 · Long answer

Identify three risks in the ClubHub architecture and how you would reduce each.

Suggested answer

Any three well-explained risks, for example:

• Leaked secret keys (Stripe, Claude, database): keep them in .env files and host settings only, never in Git or front-end code; rotate immediately if exposed.
• Unexpected costs (AI calls, emails, a bug in a loop): set spending limits and alerts, limit who can trigger paid actions and how often.
• Free-plan surprises (projects pausing or sleeping, commercial-use restrictions): read the terms, test before demos, budget for a paid plan if needed.
• Privacy: members’ emails and payment status are personal data; only officers should see sign-up lists, enforced on the back end; collect only what you need.
• Payment mistakes: use Stripe’s test mode until launch; separate development and production keys.

Question 14 · Scenario

A classmate proposes a shortcut: no back end and no database - each browser saves sign-ups in localStorage. What breaks?

Suggested answer

localStorage lives in one browser on one device. Officers couldn’t see who signed up, members couldn’t see the count or the waitlist, capacity couldn’t be enforced across members, the data would vanish when someone clears their browser or switches devices, and there would be no real login. Shared data needs a server-side database, and rules need a back end.

Question 15 · Scenario

Version 1 is live. Now officers want paid events. What changes in the architecture, and how would you develop it safely?

Suggested answer

Add Stripe: the back end creates the payment (for example a Stripe checkout) with the secret key, the browser sends the member to pay, and after a successful payment the back end marks the sign-up as paid (a new payments table or a column on signups). Develop it on a branch with a preview deployment, using Stripe’s test (sandbox) keys and test cards, keep the live secret key only in the production environment variables, and update the spec and CLAUDE.md with the new decisions.

Question 16 · Hands-on

Pick your own app idea. Start Claude Code in an empty folder in plan mode (claude --permission-mode plan) and use the first prompt on this page to get 2-3 architecture options. Then leave plan mode (press Shift+Tab), so that Claude may create files, and use the interview prompt to have it write SPEC.md. Review the result against this page’s checklist: which questions does the spec still not answer?

Suggested answer

Answers vary. A strong result has: a clear user and role list; an MVP with 3-5 features and an explicit out-of-scope list; a data model; a diagram or description of front end, back end, database, logins and third-party services; a list of keys and environment variables; a hosting and deployment plan; and a way to check that the MVP works. Commonly missing items are permissions (“who may see what”), cost limits, and what happens when a free plan pauses - add them before you start building.