78 lines
1.8 KiB
Markdown
78 lines
1.8 KiB
Markdown
# 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 |