diff --git a/TODO.md b/TODO.md index 12fa854..c92c697 100644 --- a/TODO.md +++ b/TODO.md @@ -76,8 +76,8 @@ This file is the single source of truth for roadmap and delivery progress. - [x] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow) - [x] [P1] CRUD base patterns documentation and examples - [x] [P1] Environment and deployment runbook docs (dev/staging/production) -- [ ] [P2] API and domain glossary pages -- [ ] [P2] Architecture Decision Records (ADR) structure and first ADRs +- [x] [P2] API and domain glossary pages +- [x] [P2] Architecture Decision Records (ADR) structure and first ADRs ### Delivery Pipeline And Runtime @@ -207,6 +207,7 @@ This file is the single source of truth for roadmap and delivery progress. - [2026-02-10] Public app now has a shared site layout (`banner/header/footer`), DB-backed header banner config, and SEO defaults (`metadata`, `robots`, `sitemap`). - [2026-02-10] Testing baseline now includes explicit RBAC regression checks, locale-resolution unit tests (admin/web), CRUD service contract tests, and i18n smoke e2e routes. - [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`). +- [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (`ADR 0001`). ## How We Use This File diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 7ee899f..90e3279 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -25,8 +25,10 @@ export default defineConfig({ { text: "i18n Baseline", link: "/product-engineering/i18n-baseline" }, { text: "i18n Conventions", link: "/product-engineering/i18n-conventions" }, { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" }, + { text: "Domain Glossary", link: "/product-engineering/domain-glossary" }, { text: "Environment Runbook", link: "/product-engineering/environment-runbook" }, { text: "Testing Strategy", link: "/product-engineering/testing-strategy" }, + { text: "ADR Index", link: "/adr/" }, { text: "Workflow", link: "/workflow" }, ], }, @@ -36,7 +38,17 @@ export default defineConfig({ }, { text: "Public API", - items: [{ text: "Section Overview", link: "/public-api/" }], + items: [ + { text: "Section Overview", link: "/public-api/" }, + { text: "Glossary", link: "/public-api/glossary" }, + ], + }, + { + text: "ADR", + items: [ + { text: "Index", link: "/adr/" }, + { text: "0001 Monorepo Foundation", link: "/adr/0001-monorepo-foundation" }, + ], }, ], socialLinks: [{ icon: "github", link: "https://example.com/replace-with-repo" }], diff --git a/docs/adr/0001-monorepo-foundation.md b/docs/adr/0001-monorepo-foundation.md new file mode 100644 index 0000000..dc04fe7 --- /dev/null +++ b/docs/adr/0001-monorepo-foundation.md @@ -0,0 +1,37 @@ +# ADR 0001: Monorepo Foundation + +- Status: Accepted +- Date: 2026-02-10 + +## Context + +The CMS platform requires: + +- separate admin and public apps +- shared domain contracts and data access +- consistent tooling and CI quality gates +- incremental delivery through MVP stages + +A fragmented multi-repo setup would increase coordination overhead and duplicate shared contracts. + +## Decision + +Adopt a Bun workspace monorepo with: + +- `apps/admin` and `apps/web` for runtime surfaces +- shared packages (`@cms/content`, `@cms/db`, `@cms/crud`, `@cms/ui`, `@cms/i18n`) +- shared quality tooling (Biome, TypeScript, Vitest, Playwright, Turbo) + +## Consequences + +### Positive + +- shared contract updates propagate in one change set +- easier cross-app refactors and testing +- single CI pipeline with consistent gates + +### Negative + +- stronger need for workspace discipline and clear boundaries +- larger repository clone/build surface +- potential for cross-package coupling if conventions are not enforced diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..d2ae259 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,17 @@ +# ADR Index + +Architecture Decision Records (ADRs) capture important technical decisions and context. + +## Format + +- Numbered files: `0001-.md` +- Immutable once accepted (new ADRs supersede old decisions) +- Include: + - Status + - Context + - Decision + - Consequences + +## Records + +- [0001 - Monorepo Foundation](./0001-monorepo-foundation.md) diff --git a/docs/index.md b/docs/index.md index 7a54842..04cd51a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,6 +7,7 @@ Engineering documentation hub for this repository. - [Product / Engineering](/product-engineering/) - [Admin / User Guides](/admin-user-guides/) - [Public API](/public-api/) +- [ADR Index](/adr/) ## Core Sources diff --git a/docs/product-engineering/domain-glossary.md b/docs/product-engineering/domain-glossary.md new file mode 100644 index 0000000..7358ee2 --- /dev/null +++ b/docs/product-engineering/domain-glossary.md @@ -0,0 +1,35 @@ +# Domain Glossary + +## Core Terms + +### Owner + +Highest-privilege admin role. Exactly one canonical owner must exist at all times. + +### Support User + +Hidden technical support account used for break-glass access and operational recovery. + +### Admin Registration Policy + +Runtime policy controlling whether `/register` can create additional admin users after owner bootstrap. + +### Protected Account + +Account that cannot be deleted/demoted through self-service flows (support + canonical owner). + +### CRUD Service + +Shared `@cms/crud` service abstraction combining schema validation, repository orchestration, and audit hooks. + +### Permission Scope + +RBAC access scope granularity: `own`, `team`, `global`. + +### Roadmap Source Of Truth + +`TODO.md` in repository root. Rendered in admin via `/todo`. + +### Header Banner + +Public-site announcement strip configured through `system_setting` key `public.header_banner`. diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md index 7da1df0..4decf97 100644 --- a/docs/product-engineering/index.md +++ b/docs/product-engineering/index.md @@ -10,8 +10,10 @@ This section covers platform and implementation documentation for engineers and - [RBAC And Permissions](/product-engineering/rbac-permission-model) - [i18n Conventions](/product-engineering/i18n-conventions) - [CRUD Examples](/product-engineering/crud-examples) +- [Domain Glossary](/product-engineering/domain-glossary) - [Environment Runbook](/product-engineering/environment-runbook) - [Testing Strategy Baseline](/product-engineering/testing-strategy) +- [ADR Index](/adr/) - [Workflow](/workflow) ## Scope @@ -23,6 +25,4 @@ This section covers platform and implementation documentation for engineers and ## Planned Expansions -- Domain model and glossary -- ADR (Architecture Decision Record) index - Operational playbooks (incident, rollback, recovery) diff --git a/docs/public-api/glossary.md b/docs/public-api/glossary.md new file mode 100644 index 0000000..6fab3e4 --- /dev/null +++ b/docs/public-api/glossary.md @@ -0,0 +1,43 @@ +# Public API Glossary + +## Scope + +Baseline terms for future public API design and integration discussions. + +## Terms + +### Public API + +Externally consumable endpoints intended for non-admin clients. + +### Resource + +Entity exposed by an API endpoint (for example: `page`, `media`, `news`). + +### Contract + +The stable request/response schema for an endpoint version. + +### Version + +Compatibility boundary for API contracts (for example: `v1`). + +### Authentication + +Identity verification mechanism for protected API routes. + +### Authorization + +Permission check determining whether an authenticated actor can access a resource/action. + +### Pagination + +Mechanism for splitting large result sets across requests. + +### Idempotency + +Property where repeating a request does not change final state beyond the first successful call. + +### Rate Limit + +Request threshold policy applied per consumer/time window. diff --git a/docs/public-api/index.md b/docs/public-api/index.md index e9d5336..3ca62f9 100644 --- a/docs/public-api/index.md +++ b/docs/public-api/index.md @@ -11,6 +11,11 @@ No stable public API surface is documented yet. - Add API docs when real endpoints are implemented and versioned - Use OpenAPI as source of truth for endpoint reference - Keep integration guides and authentication examples here +- Use glossary terms consistently across API specs and guides + +## Reference + +- [Public API Glossary](/public-api/glossary) ## Notes