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

[1] Mono vs poly ──▶ [2] SSOT location ──▶ [3] Folder = contract ──▶ [4] SQL = SSOT
                                                                          │
                                                                          ▼
                                       [6] Agent-friendly docs ◀── [5] Progressive refactor

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.