7.6 KiB
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
- Complete C4 coverage — All four C4 levels are documented with consistent structure across views
- Architecture as code — All 19 diagrams are maintained as PlantUML source, rendered via CI/CD pipeline
- Traceability index — A comprehensive cross-reference maps business domains to architecture artifacts, workflows, and governance documents
- Enterprise service backbone — Shared services (authentication, data, integration, audit, notifications) are architecturally defined and consistently referenced across all application component views
- 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:
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 toarchitecture/workspace/system-landscape.pumldocs/architecture/containers/platform-containers.md— missing reference toarchitecture/workspace/containers-platform.pumldocs/architecture/components/inventory.md— missing reference toarchitecture/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.