Documentation Map
This repository keeps documentation in several layers. To prevent the two long-form
trees (docs/concepts/ and docs/internals/) from drifting apart, we designate a
single canonical source and treat everything else as a curated surface over it.
Canonical source of truth
docs/internals/ is the canonical specification: Japanese, deep, and kept in sync
with the code. CLAUDE.md imports and points contributors at these documents. When a
design changes, update docs/internals/ first — it is the source of truth.
Layers
| Layer | Path | Language / Depth | Purpose | Published to site? |
|---|---|---|---|---|
| Canonical spec | docs/internals/ | JA / deep | Source-of-truth specification (domain model, event sourcing, plugin system, payment gateway). | Yes (API Reference → Internals) |
| Concepts (summary) | docs/concepts/ | EN / short | Getting-started mental model. Each page links to its canonical docs/internals/ counterpart for depth. Not a parallel spec — do not add spec detail here. | Yes (Core Concepts) |
| Architecture | docs/architecture.md | EN | System overview. Imported by CLAUDE.md. | Yes |
| Guides | docs/guides/ | EN | Task-oriented integration guides. | Yes |
| API reference | docs/api/ | EN | Type/signature reference for public APIs. | Yes (API Reference) |
| Examples | docs/examples/ | EN | Runnable walkthroughs. | Yes |
Concept ↔ canonical pairing
| Concept (summary) | Canonical (source of truth) |
|---|---|
docs/concepts/domain-model.md | docs/internals/domain-model.md |
docs/concepts/event-sourcing.md | docs/internals/event-sourcing.md |
docs/concepts/plugin-system.md | docs/internals/plugin-system.md |
docs/concepts/payment-gateway.md | docs/internals/payment-gateway.md |
Where Docusaurus publishes from
The public site (website/) is generated by Docusaurus with path: '../docs'
(website/docusaurus.config.ts). The sidebar wiring lives in website/sidebars.ts:
docs/concepts/ appears under Core Concepts and docs/internals/ under
API Reference → Internals. When adding a doc, add it to the appropriate sidebar
category.
Rules for contributors
- Change specs in
docs/internals/first (canonical). - Keep
docs/concepts/short; if it repeats spec detail, replace that with a link to the internals counterpart. - Wire any new published doc into
website/sidebars.ts.