---
name: modular-architecture
description: Restructure a project so a mistake stays contained (small blast radius) and an AI or a person can work on one module without understanding or breaking the rest: clear module boundaries, typed contracts and interfaces, separation of concerns, tests as a safety net, and git discipline. Use when a codebase is a tangle, before scaling, or to make an AI-built project safe to change.
license: Free to use with attribution to EquityFlow / Enrico Yu (equityflow.finance)
source: https://equityflow.finance/deep-dives/vibecoding-fullstack
---

# Architect a project for the long run

Use when refactoring or structuring a project (especially an AI-built one) so changes are safe. The goal:
if one part breaks, you replace that part, you do not throw away the project. Audit the codebase against
each principle below, report what is tangled, and refactor the highest-risk areas first.

## Modularization (small blast radius)
- Split the project into modules with a single responsibility each (auth, data, billing, UI, ...). A bad
  change in one must not be able to break the others. If everything imports everything, fix that first.

## Module boundaries
- Each module exposes a small, clear interface and hides its internals. The rest of the app uses
  `charge(user, amount)`, it never reaches inside the payments module. You should be able to work on one
  module knowing only its contract, not the underlying code.

## Contracts and interfaces are the glue
- Make the seams explicit: typed function signatures, API schemas (REST/GraphQL/OpenAPI), database schemas.
  Use types (TypeScript, Python type hints, Pydantic) so mismatches fail before runtime. Design the
  interface first, implement behind it.

## Separation of concerns
- Keep auth, data/persistence, business logic, the API layer and the UI as distinct, swappable layers.
  Database queries inside UI components is the anti-pattern that makes AI changes dangerous. Each concern
  can then be assigned to a different session, agent or provider.

## Cut work as vertical slices
- Prefer building one complete feature end to end (through every layer) over doing all of one layer first.
  A vertical slice is shippable, testable and contains risk.

## A spec/docs layer the AI reads
- Add an AGENTS.md / CLAUDE.md and a README per module stating conventions, architecture and the do-nots.
  Agents that read a good project doc make far fewer wrong assumptions. This is the cheapest, highest-return
  move there is.

## Tests are the safety net
- Tests let an agent change code and prove it did not break anything, so you do not re-read everything. Test
  the critical paths, the contracts, and anything involving money first. Beware tests that just assert
  whatever the code already does.

## Git discipline
- Small, frequent commits. A branch per feature/module. Review the diff before committing. Never blind-stage
  everything (an agent can stage deletions of files it did not create). Know how to revert and restore.

Output: a list of the worst couplings (file:reason), a proposed module map with the interfaces between them,
and a refactor order. Then apply the safest high-impact changes and keep tests green.

---
This skill distills EquityFlow's full-control vibecoding deep dive (https://equityflow.finance/deep-dives/vibecoding-fullstack).
EquityFlow is building an open intelligence layer for the private economy, by Enrico Yu. Free to use with attribution.