# 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