85 lines
5.1 KiB
Markdown
85 lines
5.1 KiB
Markdown
# ADR Index
|
|
|
|
Architecture Decision Records will be maintained here.
|
|
|
|
## Current State
|
|
|
|
No formal ADRs have been recorded yet. The following decisions have been identified through project analysis as candidates for retroactive ADR documentation.
|
|
|
|
!!! info "Last analyzed: 2026-05-22"
|
|
|
|
## Recommended ADRs
|
|
|
|
The following significant architecture decisions are already in effect across the platform. Recording them as formal ADRs would establish an auditable decision history and provide context for future changes.
|
|
|
|
### ADR-001 — Use C4 model with PlantUML as architecture-as-code standard
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** The platform needs a consistent architecture documentation approach that supports version control and CI/CD rendering
|
|
- **Decision:** Use the C4 model (landscape, context, container, component) with PlantUML sources maintained in `architecture/workspace/`
|
|
- **Consequences:** All 19 architecture diagrams follow this pattern; diagrams are rendered automatically via CI/CD; local preview requires PlantUML server access
|
|
|
|
### ADR-002 — Use Flutter monorepo with shared packages for cross-platform applications
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** The platform needs to support both web and Android applications with shared business logic
|
|
- **Decision:** Use a Flutter monorepo structure under `kell_creations_apps/` with shared packages (`core`, `design_system`, `feature_*`) and platform-specific app targets (`kell_web`, `kell_mobile`)
|
|
- **Consequences:** Business logic is shared; domain/application/data/presentation layers are separated per package; each app target composes its own shell and routing
|
|
|
|
### ADR-003 — Use `--dart-define` for runtime environment selection
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** The platform needs to switch between fake and real backends without code changes
|
|
- **Decision:** Use `--dart-define` keys (`KC_ENV`, `KC_WC_SITE_URL`, etc.) to select runtime environment at build time
|
|
- **Consequences:** No settings UI needed; credentials are never hardcoded; `KcBootstrap` handles fallback to fake mode when WP credentials are missing
|
|
|
|
### ADR-004 — Use MkDocs Material with Forgejo CI/CD for documentation publishing
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** The platform needs a docs-as-code publishing pipeline
|
|
- **Decision:** Use MkDocs Material as the documentation framework, published via Forgejo Actions with dedicated runners on the Ubuntu documentation host
|
|
- **Consequences:** Documentation is version-controlled; publish and validate workflows are separated by branch; the published site at `docs.kellsupport.com` is automatically updated on `main` branch pushes
|
|
|
|
### ADR-005 — Use abstract service composition pattern in `core` for cross-platform app shells
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** `kell_web` and `kell_mobile` need to share composition logic without circular dependencies
|
|
- **Decision:** Extract abstract composition types (`KcAppConfig`, `KcAppServices`, `KcServiceFactory`, `KcBootstrap`, `KcAppScope`) into the `core` package; each app target provides concrete implementations
|
|
- **Consequences:** Composition contract is enforced; circular dependencies avoided; `kell_web` retains backward-compatible typedefs; documented in `kell_creations_apps/docs/composition-strategy.md`
|
|
|
|
### ADR-006 — Maintain policy repository with controlled lifecycle and YAML front matter metadata
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** The business needs formal governance for policies, procedures, standards, and exceptions
|
|
- **Decision:** Use a Git-based policy repository with lifecycle directories (`drafts/`, `review/`, `active/`, `retired/`), YAML front matter metadata, CSV registers, and evidence retention
|
|
- **Consequences:** All controlled documents follow a defined lifecycle; metadata requirements prevent informal policy creation; registers and evidence support audit readiness
|
|
|
|
### ADR-007 — Use Forgejo Actions with dedicated runners for CI/CD pipelines
|
|
|
|
- **Status:** Accepted (in practice)
|
|
- **Context:** The platform needs automated validation and publishing for both documentation and Flutter applications
|
|
- **Decision:** Use Forgejo Actions with two runner types: a Docker runner for containerized workloads and a host runner for direct filesystem access (publishing, rsync)
|
|
- **Consequences:** Four workflows operational (`publish-docs`, `validate-docs`, `flutter-analyze`, `flutter-test`); runner tokens must be managed securely; host runner limited to narrowly defined workflows
|
|
|
|
## ADR Template
|
|
|
|
When recording new ADRs, use the following structure:
|
|
|
|
```markdown
|
|
### ADR-NNN — Title
|
|
|
|
- **Status:** Proposed | Accepted | Deprecated | Superseded
|
|
- **Context:** What is the issue that we're seeing that motivates this decision?
|
|
- **Decision:** What is the change that we're proposing and/or doing?
|
|
- **Consequences:** What becomes easier or more difficult to do because of this change?
|
|
```
|
|
|
|
## Maintenance
|
|
|
|
New ADRs should be added when:
|
|
|
|
- A significant technology, framework, or tool choice is made
|
|
- A structural or organizational pattern is established or changed
|
|
- A decision constrains future development options
|
|
- A previous ADR is superseded or deprecated
|