# 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