Skip to content

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.

Last analyzed: 2026-05-22

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:

### 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