You can now trace one user action from screen to trusted backend to data and back. The temptation at this point is to ask an AI to "design the architecture" — and receive twelve boxes, nine arrows, and a bill.

Architecture theater is the enemy

Ask an AI for "enterprise architecture for my startup" and it will comply enthusiastically. It will generate a folder for an API gateway, three microservices, two queues, a cache layer, and a Kubernetes manifest — before you have ten users. Every box looks professional. None of them earns its keep.

Call this architecture theater: complexity that performs competence instead of serving a user. It is especially easy with AI, because generating twelve service folders costs the model nothing. Operating them costs you everything: more deployments to watch, more secrets to rotate, more contracts to keep compatible, more logs to correlate when something breaks at midnight.

A small application does not need twelve services because an AI can generate twelve service folders. It needs one understandable system that does one user job well, with seams you can open later when reality demands it.

The default beginner architecture

For your first version of Research Desk — or Neighborhood Events, or almost any small AI-built product — start here:

• One application repository. One place where the whole product lives, with the branch and review discipline from Part X.
• One deployable web app. Frontend pages and backend API routes shipped together as a single unit.
• Managed database, auth, and storage where needed. Let a mature provider hold Postgres rows, sign-in sessions, and file storage behind documented controls, instead of building those yourself.
• One background worker or scheduled job only when a real task requires it. Research Desk needs a scheduled brief refresh. Neighborhood Events probably does not need any worker at all. Add the worker when a clock-driven job exists — not before.

That is the whole default. It covers search, briefs, watchlists, sign-in, and refresh without a single microservice.

A monolith is not a mess

The technical name for this default is a monolith: one deployable application containing related frontend and backend responsibilities.

Newcomers hear "monolith" as an insult — amateur, messy, unable to scale. That is wrong. A monolith describes *deployment shape*, not code quality. A well-organized monolith has clear internal modules, named contracts, tests at its seams, and a readable structure. A badly organized pile of microservices is still a pile, now with network latency between the messes.

Related responsibilities shipped together are easier to understand, test, deploy, and roll back. You can still separate code into folders and modules inside the monolith. You simply do not pay the price of separate deployments, separate versioning, and separate failure modes until one part genuinely needs to move independently.

The first Research Desk architecture

Here is the entire v1 architecture on one page:

Browser → web application → database
                     ├→ approved public-data provider
                     ├→ authentication service
                     └→ scheduled refresh job

Read it as a sentence: the person uses the browser; the browser talks only to your web application; the application reads and writes the database, calls the approved market and filing provider with a secret the browser never sees, delegates sign-in to the authentication service, and lets a scheduled refresh job update stale briefs.

Draw this before you prompt any worker. Every later decision — a new table, a new route, a new provider — is a change to this picture, reviewed like any other change. If an AI proposes a system that is not on this picture, it must justify adding it.

The test for adding a boundary

Separate a component into its own service only when it has a need that is real today:

1. A distinct responsibility that changes for different reasons on a different rhythm. 2. A scaling, security, or deployment need that the shared app cannot satisfy — for example, a long-running private job that exceeds web-request limits. 3. An ownership need — a separate team must deploy it without coordinating every release.

"The AI said microservices are modern" is not a reason. "We might need it someday" is not a reason. "Our first 1,000 users" almost never needs more than the default above.

Apply the test to Research Desk: search traffic, brief rendering, and watchlist saves all change together, deploy together, and serve the same users. They stay inside the web app. The scheduled refresh runs on a clock with different failure modes, so it earns its one separate job box — with a narrow write permission, covered properly in Class 47.

Bad prompts and better prompts

Architecture quality starts in the prompt.

Bad:

This invites theater. No user flow, no scale, no constraints — so the model fills the vacuum with boxes.

Better:

Notice what the better prompt does: it pins the model to one flow, caps the scale, demands assumptions and risks, and forces every extra box to carry a justification. You stay the architect. The AI stays the drafter.

A second useful prompt: "Review this ARCHITECTURE.md against the user flow. Flag any component no flow uses, any arrow with no contract, and any secret the browser could reach. Propose deletions first."

Practical exercise: write ARCHITECTURE.md

Create ARCHITECTURE.md at your repository root. Keep it to one page:

1. Components — web app, database, auth service, provider, refresh job. One line each: what it does, what it never does. 2. Owners — who may change each component (you, a named agent role, a provider you do not control). 3. Data paths — the arrows from the diagram, each naming the request direction and the shape carried. 4. Secrets — which secrets exist, where each lives (server configuration, never the browser bundle), and who can rotate them. 5. External services — each provider, what it supplies, its quota and failure behavior. 6. Three explicit non-goals — things you are deliberately not building. Example: no second backend service, no custom auth server, no real-time streaming pipeline.

Finish line: an ARCHITECTURE.md plus the five-line diagram above, readable by a non-engineer and precise enough that an AI worker can build against it without inventing new systems.

Verify: hand only the file to a friend (or a fresh AI session). Ask: "Where does the provider key live? Which box writes the watchlist? What triggers the refresh job?" If they guess, the file is vague.

Common failure mode: writing goals but no non-goals. Without non-goals, every enthusiastic agent re-adds the queue, the cache, and the second database "for best practices."

Check your understanding

1. Why is generating twelve services nearly free for an AI but expensive for you? 2. What are the four parts of the default beginner architecture? 3. What does "monolith" actually mean — and what does it not mean? 4. State the real-today test for adding a new service boundary. 5. What must your ARCHITECTURE.md contain, and why do non-goals matter?