Monorepo · SSOT · layer separation thinking

Past three services, structural decisions start to weigh more than any individual library choice. Monorepo · SSOT · layer separation form the base that removes "we have to change the same function in three places" fatigue.

Who it's for

• Developers running several side projects out of one place
• People who feel "the same code runs in three spots"
• Teams making architectural calls by gut feeling

What you can do afterwards

• Choose between monorepo and polyrepo deliberately
• Place the Single Source of Truth where it belongs
• Treat folders as contracts · maintain "URL = folder" integrity
• Run SQL as SSOT · DB is a mirror
• Apply progressive refactoring and trade-offs
• Write documentation that works for humans and agents

Flow

How structural decisions become durable

1Repository boundary

Compare ownership and deployment coupling in mono- and multi-repository systems.

2Single source

State whether code, configuration, or data is authoritative for each contract.

3Physical contract

Let folder boundaries and SQL schemas expose responsibility and data ownership.

4Progressive improvement

Evolve the structure safely through small refactors and decision-focused documentation.

Later steps share a pattern: "the result of the decision lives outside the code" — folder shape, DB schema, documents.

Steps

1. Monorepo vs polyrepo — code sharing · CI · releases · team boundaries
2. SSOT — where to put it — code · DB · docs as choices
3. Folders as contracts — URL = folder · naming conventions · stable entry points
4. SQL = SSOT — DB schema as truth · ALTER strategy · idempotent seeding
5. Progressive refactor · trade-offs — rules that keep big rewrites at bay
6. Agent-friendly documentation — CLAUDE.md · rules.md · skills · semantic naming

Prerequisites — experience running at least two services.