| name | architectures |
| description | Architecture pattern reference for Next.js & React projects. Covers Flat, Feature-Based, FSD, and Monorepo patterns with core principles, file placement, and import boundaries. |
Architecture Patterns
Reference guide for choosing and applying architecture patterns. Used by the /init agent when generating spec/ARCHITECTURE.md.
Pattern Summary
| Pattern | Team size | Core idea | When to use |
|---|
| Flat | Solo | Root-level sharing, no feature grouping | Prototypes, simple apps, < 10 features |
| Feature-Based | Small (2-5) | Self-contained feature modules with public API | Clear feature boundaries, medium complexity |
| FSD | Medium (5-15) | Strict unidirectional layer hierarchy | Complex domain logic, strict discipline needed |
| Monorepo | Large (15+) | apps/ + packages/ with Turborepo | Multiple apps, shared code, independent deploys |
How to Choose
Is this a solo prototype or simple app?
├─ Yes → Flat
└─ No → Does the team need strict layer rules?
├─ Yes → Is the team 15+?
│ ├─ Yes → Monorepo
│ └─ No → FSD
└─ No → Feature-Based
Migration Path
Flat → Feature-Based → FSD → Monorepo
Each pattern is a superset of the previous. Migration is incremental — you don't need to rewrite everything at once.
Agent Usage
/init reads the detected pattern and applies the corresponding guide when writing spec/ARCHITECTURE.md- Agents reference this skill for file placement and import boundary decisions
- The pattern guide is a reference — agents adapt to the actual project structure, not the other way around
