Project Architecture

Project architecture

The first hour of a project decides whether it scales. Folders are the easy part; the hard part is ownership: who is allowed to know about what. A codebase where the UI can reach Stripe, or where page.tsx calls the ORM directly, does not get better with time. It gets bigger.

This matters more with coding agents than without them. An agent reads the conventions already in the repo and builds on top of them. Bad structure does not stay bad at constant size; it compounds. Set the boundaries first and the agent's shortcuts become impossible rather than merely discouraged.

Which is why this skill has a second job. Conventions decided in week one are forgotten by week six, by the agent whose context has rolled over and by the human who moved on. Bootstrap builds the architecture. Convention keeps it.

Pick the mode

Everything version-specific is a moving target

references/ holds distilled architecture knowledge: layering, the dependency rule, DAL/DTO/policy, ERD design and migrations, tenant isolation, API contracts, list views, mutations, accessibility, async work, uploads, security, performance, operations, lint guardrails and design tokens. Those principles hold across versions.

Every concrete API, file name, flag, and command in them is a moving target. The reference files mark those with VERIFY: blocks stating exactly what to look up. Resolve them against the live docs before writing code, in both modes, not just at bootstrap. Context7 goes through Executor; see the mcp-integrations skill for the tool path and the two-step flow. Read the version attached to whatever comes back: it is the difference between "the docs say X" and "the docs for the version installed here say X".

Never write code from what a reference file, or your training data, implies the current API is. Live example: Next.js renamed middleware to proxy, and now ships its own docs inside node_modules/next/docs. Anything that hardcoded those is already wrong.

When the live docs contradict a reference file, the docs win and you say so out loud. If a reference file's principle no longer has a mechanism in the current version, say that too rather than inventing one.

The non-negotiables

The compressed form of the rules, for recall. Each one expands in the reference file named; that file is the authority.

1. The dependency rule. UI → Transport → Domain → Capabilities → Vendors, each layer reaching only the one below it. Shared contracts and the database client flow upward to everyone. (architecture.md)
2. The DAL is the only path to the database. No ORM call in a page, a component, a route handler, or an action. (data-layer.md)
3. In a multi-tenant product, the tenant is a required argument. Never optional, never inherited, never taken from a client-controlled value. This covers jobs, caches and storage keys, not just queries. (multi-tenancy.md)
4. Authorization before data, next to the data. Upstream gates are an optimization, not the security model. (data-layer.md)
5. Validate in and out. Inputs because users lie; outputs because the database returns more than the client should see. (data-layer.md)
6. Server-only is a build error, not a convention. Sensitive modules import the server-only marker so a client import fails loudly. (security.md)
7. Every entry point is public. A server action compiles to a POST endpoint; arriving through your form is not a fact you get to assume. (security.md)
8. Server Components by default. "use client" lives on the leaves, only where there is interactivity. (performance.md)
9. One contract, both directions. The schema is the single source of truth for input, output, types and docs. (api-design.md)
10. The state of a view lives in the URL. Filters, sort, search and page are query params, parsed against a schema. State trapped in a component is a view nobody can share, bookmark or restore. (list-views.md)
11. A boundary that is not linted is a preference. The dependency rule is only real once an illegal import fails the build. (lint-guardrails.md)
12. A URL that has been shared is a contract. Do not encode a movable relationship in a path, and never let a rename silently kill existing links. (url-design.md)
13. The right element before any ARIA. Native elements carry role, focus and keyboard behavior; a div reimplementing them is a permanent debt. Focus and announcements are owned, not assumed. (accessibility.md)
14. Semantic tokens, never literal colors. bg-primary, not bg-blue-500. (design-system.md)
15. One naming format. kebab-case for source files, snake_case in the database. (architecture.md, database.md)

Bootstrap

Create a todo per phase. Do not skip phase 3's checkpoint.

1. Discovery

Understand the product before touching the stack. Ask only what you cannot infer, and ask it through the AskUserQuestion selector per the global CLAUDE.md rules: tenancy, profile and everything already decided are enumerable, so they are tabs. Only the mini-PRD paragraph is genuinely open, so that one goes in prose after the selector.

• What is it? One paragraph. This becomes the mini-PRD.
• Features in scope. A list. Every noun in it is a candidate entity.
• Who are the users, and does it have tenancy? Single-user, multi-user, or multi-tenant (organizations/workspaces). This one decision reshapes the whole schema, and if the answer is multi-tenant, references/multi-tenancy.md governs the model before anything else does.
• What is already decided? Deployment target, database, auth provider, payments, anything the user already pays for or knows they want.
• Does anything run outside a request? Uploads, scheduled work, emails, exports, anything slow. These need a home in the blueprint rather than an improvised one later. Per references/async-work.md and references/file-uploads.md.

Then pick the profile, and say which one you picked and why:

Do not default to the monorepo. It is the right end state for a product with real scale, and premature weight for anything smaller. The layering principles are identical in both; only the enforcement mechanism differs (folders + lint vs. package boundaries).

2. Version verification

Resolve, at minimum:

• The framework. Current major, what the CLI creates today, which conventions were renamed or removed, which config flags the planned features need.
• The ORM / database client. Current schema syntax, id generation, migration commands.
• The auth provider, if any. Current session API and its server-side entry point.
• The component library. Current CLI command and init flow.
• The transport layer, if the project exposes an external API. Current setup for the typed-RPC library and its OpenAPI handler.

Then walk references/ and resolve every VERIFY: block that applies to the chosen stack. Record the resolved versions: they go in the blueprint and in AGENTS.md.

3. Blueprint, then stop

Present, compactly:

1. Mini-PRD: the paragraph and the feature list.
2. Entities and ERD: tables, fields, keys, relationship types. Per references/database.md. Present as a diagram or a clear list; this is the piece most worth getting right before any code exists.
3. The route space: the URLs the product will have, where the tenant sits in them, and what identifies a resource. Per references/url-design.md. It belongs in the blueprint rather than emerging from the folder tree, because URLs become a public contract the moment anyone shares one.
4. Folder tree: the actual tree you will create, per references/architecture.md and the chosen profile.
5. Stack and exact versions: resolved in phase 2, plus anything the live docs corrected.
6. What you will not do: explicitly out of scope for this scaffold.

Then stop and wait for approval, asked through the selector (approve as-is / revise the entities / revise the stack). Do not scaffold before the user approves. If they change the entities or the stack, revise and present again.

4. Scaffold

In this order, so the project works end to end at every step:

1. Run the framework CLI with the flags verified in phase 2. Let it create what it creates; do not fight it.
2. Apply the folder structure from the approved blueprint. Empty directories are fine as placeholders only if something in them is coming in this same scaffold; otherwise leave them out.
3. Database schema from the approved ERD, plus the initial migration. Verify it applies.
4. Design system: install the component library, set semantic tokens in the global stylesheet, configure dark mode. Per references/design-system.md.
5. Guardrails, before the slice. Copy the preset from lint/ in the dotfiles repo: oxlint.config.ts, .oxfmtrc.json, tools/oxlint/ and rule-tests/, plus ci.yml into .github/workflows/. Its README.md has the five install steps; references/lint-guardrails.md has the reasoning. Adapt the boundaries block and its fixtures to this project's layer names, then run node tools/oxlint/rule-tests/check.mjs — a boundary table nobody verified is a boundary table that may be denying everything or nothing. Guardrails go in first so the vertical slice is the first thing checked against them; boundary rules added after twenty files exist are boundary rules you weaken to make the build pass.
6. One vertical slice. Pick a single real entity from the ERD and build it all the way through: DTO, policy, DAL, action, and a page that renders it. This is the template every future feature copies, and it is what proves the architecture actually runs. Per references/data-layer.md. If the entity has a list — and most do — build the list the way references/list-views.md describes and the write the way references/mutations.md does, because whatever this slice does is what every later feature will copy. The URL-state dependency enters here and only here: install it when the slice actually has filters to put in the URL, not as part of the baseline, so a project without a list never carries it. Run the tdd skill here. The slice is the template every later feature copies, so whatever testing habit it establishes is the one the project keeps: a slice shipped without a test teaches the agent that features do not come with tests.
7. Security baseline: security headers, the server-only markers, environment variable split, locked-down install scripts. Per references/security.md.
8. Configuration and logging: the environment schema that fails the build when a variable is missing, plus structured logging with a trace id. Per references/operations.md.
9. AGENTS.md at the repo root, documenting conventions, the dependency rule, and the resolved versions. A CLAUDE.md that points at AGENTS.md rather than duplicating it.

5. Verify

Run the build, the linter, node tools/oxlint/rule-tests/check.mjs, and the slice's tests. The four must pass. If the vertical slice has a page, run the dev server and confirm it renders.

Then audit the repo against the non-negotiables:

python <skill>/scripts/audit_project.py --path .

It reports three things, and the last two are different. MISSING is something the repo says is absent. BY HAND is a non-negotiable with a semantic signature that no tool can decide, which is exactly the kind that gets quietly dropped when a session's context rolls over. A BY HAND line is not a pass, it is the list of what still needs a person. Walk it before reporting the bootstrap done.

Report what was created, the resolved versions, anything the live docs corrected, and what is deliberately left for later. Do not claim it works without the command output.

Convention

The failure this mode exists to prevent: an agent six weeks in, writing a query straight into a page component because nothing in its context said not to.

Order of authority

1. AGENTS.md at the repo root. This is the project's own record: resolved versions, layer names, the illegal imports, the domain vocabulary, where a new feature goes. Read it before answering anything architectural.
2. The code already there. One existing module of the same kind outranks any general rule. Copy its shape.
3. references/. The principle behind the rule, and the answer when the repo is silent.

When the repo contradicts a reference file, the repo wins and you say so. A project that deliberately diverged is not a project that made a mistake. When the repo is silent, apply the reference and offer to write the decision into AGENTS.md.

The procedure

0. Audit first when you are new to the repo. python <skill>/scripts/audit_project.py --path . gives you, in one pass, which non-negotiables are in place and which are not. Cheaper than reading nineteen references to find out the project never had lint boundaries.
1. Read AGENTS.md. If there is none, say so: the project has no written conventions, and writing one is usually the highest-value next move. Per references/architecture.md.
2. Name the layer. Answer "who should be allowed to know about this?" before "where does this file go?". The layer decides the folder, not the other way around.
3. Open the one reference for the concern, not all nineteen. The table below maps concern to file.

When the question is not this skill's

Three questions arrive dressed as architecture questions and are answered better elsewhere. Hand them over instead of improvising:

They are siblings, not alternatives: a diagnosis usually ends in a regression test, and a deepened module usually changes what the tests attach to. 4. Resolve the VERIFY: blocks that apply against the live docs before writing any code. A principle that is right and an API that is stale still produces a broken file. 5. Point at the closest existing example in the repo and match it: naming, file split, order of operations inside the function.

Keeping AGENTS.md alive

A convention that only lives in this skill is a convention the next session loses. When work establishes something durable (a new layer, a chosen library, a rule you had to explain twice), write it into AGENTS.md in the same change. Keep CLAUDE.md a pointer at AGENTS.md; two copies of the conventions means one of them is stale.

Reference files

Read the one the work is about. Reading all nineteen for a question about a foreign key wastes the context the actual task needs.