Architecture

Treat the directory tree as a map of runtime boundaries, ownership, and allowed dependencies. Optimize for the next maintainer finding and changing code safely, not for visual symmetry.

Apply these rules

• Preserve repository instructions, framework-reserved paths, build-tool conventions, and established domain language unless a change has a concrete payoff.
• Group product code primarily by business capability or feature. Use technical layers inside a capability when they clarify dependency direction.
• Give every module one purpose, one public surface, and private implementation details.
• Make dependencies explicit, acyclic, and enforceable. Do not rely on folders alone.
• Keep code with the feature, team, test suite, and deployment unit that change together.
• Promote code to shared space only after genuine reuse and stable semantics exist.
• Keep entry points, routes, controllers, and framework adapters thin. Put decisions in application or domain modules.
• Separate generated artifacts, migrations, fixtures, operational configuration, and source code.
• Prefer a well-bounded modular monolith until independent deployment, scaling, reliability, security, or ownership requirements justify services.
• Use the shallowest tree that preserves meaningful boundaries. Do not create one-file directories or speculative abstractions.
• Describe recommendations as a synthesis of public practices. Never present a sample tree as “the Google structure” or “the Meta structure.”

Follow the workflow

1. Discover constraints

For an existing repository:

1. Read local instructions and architecture records.
2. Inspect the tree, manifests, workspace/build configuration, import aliases, entry points, routes, persistence code, tests, deployment files, and ownership rules.
3. Identify the framework's mandatory structure and the repository's current dependency direction.
4. Find code that changes together, duplicated “shared” code, cross-boundary imports, cycles, oversized directories, and ambiguous names.
5. Preserve unrelated user changes.

For a greenfield repository, infer only reversible defaults. Ask about a missing constraint only when it would materially change repository topology, deployment boundaries, data ownership, or framework choice.

2. Select a topology

Choose the smallest topology that fits:

• Use a single application repository for one deployable with little reusable code.
• Use a modular monolith for a growing backend with several business capabilities but one practical deployment boundary.
• Use a monorepo when multiple apps or packages require atomic changes, shared tooling, and coordinated dependency management.
• Use multiple repositories or services only when independent lifecycle or access boundaries outweigh coordination cost.

Read repository-topologies.md before choosing or changing repository topology.

3. Define boundaries before names

For each proposed module, state:

• responsibility and owning business capability;
• public API or entry point;
• private implementation area;
• owned state, schema, or external integration;
• allowed incoming and outgoing dependencies;
• test boundary;
• runtime and deployment boundary, if any.

Resolve unclear ownership before inventing directories. Use domain terms such as billing, catalog, or identity; avoid vague buckets such as common, helpers, misc, or manager.

Read core-principles.md for dependency rules, scale calibration, naming, tests, and enforcement.

4. Adapt the concrete layout

• For browser, mobile-web, React, Vue, Angular, Svelte, or route-driven UI work, read frontend.md.
• For APIs, workers, jobs, modular monoliths, event consumers, or services, read backend.md.
• For full-stack work, read both references and then place deployables and reusable packages using repository-topologies.md.
• When citing or deliberately borrowing large-company practices, read public-patterns.md.

Adapt examples to the detected language and framework. Do not force a generic src/ tree over conventions such as Next.js route segments, Rails engines, Django apps, Go packages, Java source sets, or .NET projects.

5. Produce or implement the result

When asked for a recommendation, return:

1. assumptions and constraints;
2. the selected topology and why;
3. an annotated target tree;
4. allowed and forbidden dependency directions;
5. public module surfaces and ownership;
6. testing, configuration, generated-code, and operational placement;
7. trade-offs and rejected alternatives;
8. an incremental migration sequence for existing code;
9. automated enforcement to prevent regression.

When asked to change code:

1. Move one coherent boundary at a time.
2. Update imports, package/build declarations, aliases, tests, fixtures, ownership files, and documentation in the same change.
3. Add compatibility exports or adapters when a staged migration needs them.
4. Avoid mixing structural moves with unrelated behavior changes.
5. Remove obsolete paths only after callers migrate.

6. Validate

Run the repository's formatter, type checker, tests, build, and architecture rules. Also verify:

• no unexpected dependency cycles or deep imports into module internals;
• production code does not depend on test helpers;
• shared code does not depend on product features;
• backend domain/application code does not depend directly on delivery frameworks;
• frontend shared UI does not own feature workflows;
• every deployable has an obvious entry point, configuration boundary, health/observability integration, and test path;
• generated output and secrets are not treated as hand-maintained source;
• the resulting tree remains navigable without empty placeholder layers.

If automated boundary tooling is unavailable, document a simple import rule and add the narrowest lint, build, or test enforcement the stack supports.

Review rubric

Judge a structure by these questions:

• Can a new contributor identify where a feature starts within a minute?
• Can a feature be changed without editing unrelated global buckets?
• Can module internals change without breaking callers?
• Does the dependency graph match the intended architecture?
• Are ownership, state, tests, and operations located near the code they govern?
• Can a module grow, split, or be extracted without a repository-wide rewrite?
• Is every shared abstraction backed by real consumers?
• Does framework upgrade guidance still apply without fighting the layout?

Do not approve a structure merely because its tree looks tidy. Approve it when boundaries are understandable, dependencies are controlled, and routine changes stay local.