diff --git a/docs/operations/architecture-workflow.md b/docs/operations/architecture-workflow.md new file mode 100644 index 0000000..a762ebe --- /dev/null +++ b/docs/operations/architecture-workflow.md @@ -0,0 +1,78 @@ +# Architecture Workflow + +This document defines the standard process for creating, updating, and publishing architecture diagrams and supporting documentation for the Kell Creations Platform. + +## Purpose + +The goal of this workflow is to ensure: + +- Consistent use of C4 modeling across all architecture artifacts +- Diagram source is maintained as code (PlantUML) +- Documentation is maintained as code (MkDocs) +- All changes are version-controlled and auditable +- Published documentation remains synchronized with source + +## Tools and Platforms + +- VS Code (Windows 11) — Authoring environment +- PlantUML Server — https://plantuml.kellsupport.com +- Forgejo Git — https://git.kellsupport.com +- MkDocs Material — Documentation framework +- Docs Site — https://docs.kellsupport.com +- Ubuntu Server — Build and publishing host + +## Architecture Standards + +The platform uses C4 modeling: + +1. System Landscape +2. System Context +3. Container +4. Component + +Supplementary diagrams may include: + +- Deployment diagrams +- Dynamic (sequence/workflow) diagrams +- Data models + +## Directory Structure + +- Diagram source: + - `architecture/workspace/*.puml` + +- Documentation pages: + - `docs/architecture/...` + +## Workflow Steps + +### 1. Create or update diagram (Windows) + +- Create or modify `.puml` file in: + - `architecture/workspace/` +- Follow C4 modeling conventions +- Use shared includes (C4-PlantUML) + +### 2. Verify diagram renders (Windows) + +- Open `.puml` file in VS Code +- Press: + - `Alt + D` +- Confirm diagram renders correctly using: + - `https://plantuml.kellsupport.com` + +### 3. Create or update documentation page (Windows) + +- Create or update corresponding Markdown file under: + - `docs/architecture/...` +- Include: + - Purpose + - Scope + - Diagram source reference + - Key components or systems + - Notes + +### 4. Validate repository state (Windows) + +```powershell +git status \ No newline at end of file