# Architecture Overview

This section documents the Kell Creations platform using C4 modeling, PlantUML, and supporting technical documentation.

## Architecture Model

The platform architecture follows the C4 model with five distinct view types:

| Level | View             | Purpose                                                         |
| ----- | ---------------- | --------------------------------------------------------------- |
| 1     | System Landscape | Highest-level view of the platform and its external environment |
| 2     | System Context   | Platform boundary with users and external systems               |
| 3     | Container        | Major application and shared-service containers                 |
| 4     | Component        | Internal structure of each application container                |
| —     | Dynamic          | Cross-application workflow and sequence diagrams                |
| —     | Deployment       | Runtime topology and infrastructure                             |

## Architecture Artifacts

All architecture diagrams are maintained as code using PlantUML (C4-PlantUML) in `architecture/workspace/`. Documentation pages in `docs/architecture/` provide narrative context, included elements, and notes for each diagram.

### Current inventory

| Category         | Count  | Files                                                                                                |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| System Landscape | 1      | `system-landscape.puml`                                                                              |
| System Context   | 1      | `context-kellcreations-platform.puml`                                                                |
| Container views  | 6      | Platform containers, enterprise services, data, identity & access, integration, audit                |
| Component views  | 5      | Inventory, MRP, WordPress management, social media, financial analysis                               |
| Dynamic views    | 5      | Order-to-fulfillment, product publishing, social campaign, inventory-to-production, policy lifecycle |
| Deployment views | 1      | Production deployment                                                                                |
| **Total**        | **19** | All maintained as PlantUML in `architecture/workspace/`                                              |

## Analysis Findings

!!! info "Last analyzed: 2026-05-22"

The following findings were identified through a full review of the architecture documentation, PlantUML sources, and cross-referencing with the application codebase.

### Confirmed strengths

1. **Complete C4 coverage** — All four C4 levels are documented with consistent structure across views
2. **Architecture as code** — All 19 diagrams are maintained as PlantUML source, rendered via CI/CD pipeline
3. **Traceability index** — A comprehensive cross-reference maps business domains to architecture artifacts, workflows, and governance documents
4. **Enterprise service backbone** — Shared services (authentication, data, integration, audit, notifications) are architecturally defined and consistently referenced across all application component views
5. **CI/CD integration** — PlantUML rendering is integrated into the publish and validate workflows with automatic SVG generation

### Issues identified

#### 1. Enterprise Data Architecture — wrong diagram reference

**Severity:** High

The file `docs/architecture/containers/enterprise-data-architecture.md` references the wrong SVG image:

```markdown
![Enterprise Shared Services](../../images/containers-enterprise-services.svg)
```

This should reference `enterprise-data-architecture.svg` instead. The corresponding PlantUML source file exists (`enterprise-data-architecture.puml`) but the documentation page displays the enterprise services diagram instead of the data architecture diagram.

**Recommendation:** Fix the image reference to point to the correct SVG.

#### 2. Missing diagram source references

**Severity:** Low

The following documentation pages do not include a "Diagram Source" section pointing to their PlantUML file:

- `docs/architecture/system-landscape.md` — missing reference to `architecture/workspace/system-landscape.puml`
- `docs/architecture/containers/platform-containers.md` — missing reference to `architecture/workspace/containers-platform.puml`
- `docs/architecture/components/inventory.md` — missing reference to `architecture/workspace/components-inventory.puml`

All other architecture documentation pages include this reference consistently. These three should be updated for consistency.

#### 3. ADR index is empty

**Severity:** Medium

The Architecture Decision Record (ADR) index exists at `docs/architecture/decisions/index.md` but contains no entries. Several significant architectural decisions have already been made and should be captured:

**Recommended initial ADRs:**

| ADR     | Decision                                                                            |
| ------- | ----------------------------------------------------------------------------------- |
| ADR-001 | Use C4 model with PlantUML as architecture-as-code standard                         |
| ADR-002 | Use Flutter monorepo with shared packages for cross-platform applications           |
| ADR-003 | Use `--dart-define` for runtime environment selection (fake vs. real backends)      |
| ADR-004 | Use MkDocs Material with Forgejo CI/CD for documentation publishing                 |
| ADR-005 | Use abstract service composition pattern in `core` for cross-platform app shells    |
| ADR-006 | Maintain policy repository with controlled lifecycle and YAML front matter metadata |
| ADR-007 | Use Forgejo Actions with dedicated runners for CI/CD pipelines                      |

#### 4. Architecture-to-implementation gap

**Severity:** Medium

The architecture documentation describes rich capabilities across all five business domains, but actual implementation maturity varies significantly. Only `feature_wordpress` has substantial implementation. This creates a risk that architecture documentation may be perceived as describing current state rather than target state.

**Recommendation:** Add a clear "implementation status" or "maturity" indicator to each component view documentation page, or maintain a single cross-reference (already partially addressed by the feature maturity matrix in the master development brief).

#### 5. No architecture for the documentation platform itself

**Severity:** Low

The deployment view covers the documentation publishing infrastructure, but there is no component-level architecture for the documentation platform itself (MkDocs, PlantUML server, Forgejo runners, published site). Given the CI/CD complexity already documented in the operations section, a lightweight component view could help operational clarity.

#### 6. Images directory not committed to Git

**Severity:** Informational

The `docs/images/` directory does not exist in the repository. SVG images are generated at CI/CD time by the publish and validate workflows. This is by design — the workflows create the directory, render PlantUML to SVG, and copy files before the MkDocs build. This is architecturally sound but means local MkDocs builds without running the PlantUML render step will have broken image references.

**Recommendation:** Document this behavior in the architecture workflow documentation so new contributors understand that `docs/images/` is a build artifact, not a committed directory.

## Related Pages

- [Architecture Principles](principles.md)
- [Traceability Index](traceability-index.md)
- [ADR Index](decisions/index.md)