59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
|
---
|
||
|
|
name: docs-folder
|
||
|
|
description: Route non-hexagonal files to docs/ folder to keep domain architecture clean
|
||
|
|
---
|
||
|
|
|
||
|
|
# Docs Folder Rule
|
||
|
|
|
||
|
|
Any file that does not fit the hexagonal architecture design pattern MUST live in the `docs/` folder. The source tree stays clean — only hexagonal-compliant code belongs in `src/`.
|
||
|
|
|
||
|
|
## Hexagonal Architecture Recap
|
||
|
|
|
||
|
|
```
|
||
|
|
src/
|
||
|
|
├── domain/ # Pure business logic, entities, value objects, ports (interfaces)
|
||
|
|
├── application/ # Use cases, orchestration, input/output ports
|
||
|
|
├── infrastructure/ # Adapters — DB, HTTP clients, messaging, external APIs
|
||
|
|
└── interfaces/ # Controllers, routes, CLI, resolvers (driving adapters)
|
||
|
|
```
|
||
|
|
|
||
|
|
Only code that fits one of these layers belongs in the source tree.
|
||
|
|
|
||
|
|
## What goes in `docs/`
|
||
|
|
|
||
|
|
| Item | Why it's not hexagonal |
|
||
|
|
|------|----------------------|
|
||
|
|
| Architecture decision records (ADRs) | Documentation, not code |
|
||
|
|
| API documentation / OpenAPI specs | Reference material |
|
||
|
|
| Database diagrams / ERDs | Design artifacts |
|
||
|
|
| Flowcharts / sequence diagrams | Visual documentation |
|
||
|
|
| Meeting notes / technical decisions | Project context |
|
||
|
|
| Onboarding guides | People documentation |
|
||
|
|
| RFC / proposal documents | Decision records |
|
||
|
|
| Scratch files / experiments | Not production code |
|
||
|
|
| Third-party integration guides | Reference material |
|
||
|
|
| Deployment runbooks | Ops documentation |
|
||
|
|
| Configuration examples / templates | Not domain logic |
|
||
|
|
| Migration guides / upgrade notes | Process documentation |
|
||
|
|
|
||
|
|
## Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
docs/
|
||
|
|
├── adr/ # Architecture Decision Records
|
||
|
|
├── api/ # API specs, OpenAPI/Swagger files
|
||
|
|
├── diagrams/ # ERDs, flowcharts, sequence diagrams
|
||
|
|
├── guides/ # Onboarding, deployment, migration guides
|
||
|
|
├── rfcs/ # Proposals and RFCs
|
||
|
|
└── notes/ # Meeting notes, scratch, experiments
|
||
|
|
```
|
||
|
|
|
||
|
|
## Non-negotiables
|
||
|
|
|
||
|
|
1. NEVER put documentation files in `src/` — they pollute the domain.
|
||
|
|
2. NEVER put scratch code, experiments, or spikes in `src/` — use `docs/notes/` or a separate branch.
|
||
|
|
3. NEVER put config examples or templates in `src/` — use `docs/` or project root.
|
||
|
|
4. If a file doesn't implement a port, adapter, use case, or entity — it doesn't belong in `src/`.
|
||
|
|
5. Keep `docs/` organized by category, not by date or author.
|
||
|
|
6. README at project root is fine — detailed docs go in `docs/`.
|