kell_creations/docs/operations/architecture-workflow.md

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)

git status