Skip to content

README.md

Latest commit

 

History

History
173 lines (126 loc) · 5.86 KB

README.md

File metadata and controls

173 lines (126 loc) · 5.86 KB
Raw

A.R.C. CLI Architecture Diagrams

Visual documentation of A.R.C. CLI architecture, patterns, and workflows.

All diagrams include:

  • Mermaid code - Renders in GitHub, GitLab, and most markdown viewers
  • Eraser.io prompt - For generating polished images
  • Key files - Links to relevant source code

Quick Reference

Category Diagrams Purpose
A: Architecture 5 System structure and boundaries
B: Data Flow 4 How data moves through the system
C: Patterns 3 Design patterns used in codebase
D: Workflow 3 Processes and sequences

Category A: Architecture Diagrams

ID Name Description
A1 CLI System Architecture Entry point → Config → Context → Commands → Output
A2 Two-Brain Separation Go CLI (Infrastructure) ↔ Python SDK (Intelligence)
A3 XDG Directory Layout Config/Data/State/Cache separation
A4 Dependency Injection Flow Factory Pattern context creation
A5 Service Orchestration Catalog → Dependencies → Startup

Category B: Data Flow Diagrams

ID Name Description
B1 Command Execution Pipeline User input → Output flow
B2 Configuration Precedence Flags → Env → File → Defaults
B3 Workspace Init Flow arc init wizard steps
B4 Arc Run Lifecycle Full platform launch flow

Category C: Pattern Diagrams

ID Name Description
C1 Repository Pattern Interface → Implementation abstraction
C2 UI Service Pattern Centralized themed output
C3 Gardener Pattern Intent → Generate → Observe → Reconcile

Category D: Workflow Diagrams

ID Name Description
D1 CLI Command Tree Command hierarchy
D2 SpecKit Workflow Specify → Plan → Tasks → Implement
D3 Service Startup Sequence Dependency-ordered boot

Generating Images

Option 1: Mermaid (Automatic)

Mermaid diagrams render automatically in:

  • GitHub README/issues/PRs
  • GitLab markdown
  • VS Code with Mermaid extension
  • Docusaurus (with plugin)

Option 2: Eraser.io (Manual)

For polished, shareable images:

  1. Go to eraser.io
  2. Create new diagram
  3. Paste the Eraser.io prompt from any diagram file
  4. Export as PNG/SVG
  5. Save to docs/diagrams/images/

Option 3: Mermaid CLI (Automated)

# Install mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# Generate PNG from markdown
mmdc -i A1-cli-system-architecture.md -o images/A1.png

File Structure

docs/diagrams/
├── README.md                           # This index
├── VOTING.md                           # Diagram voting tracker
├── A1-cli-system-architecture.md
├── A2-two-brain-separation.md
├── A3-xdg-directory-layout.md
├── A4-dependency-injection-flow.md
├── A5-service-orchestration.md
├── B1-command-execution-pipeline.md
├── B2-configuration-precedence.md
├── B3-workspace-init-flow.md
├── B4-arc-run-lifecycle.md
├── C1-repository-pattern.md
├── C2-ui-service-pattern.md
├── C3-gardener-pattern.md
├── D1-cli-command-tree.md
├── D2-speckit-workflow.md
├── D3-service-startup-sequence.md
└── images/                             # Generated images (optional)
    ├── A1.png
    ├── A2.png
    └── ...

Diagram Standards

All diagrams follow these conventions:

Colors

Element Color Hex
Primary/Entry Purple #6a1b9a
Secondary Blue #1565c0
Success/Complete Green #2e7d32
Warning/Highlight Yellow #f9a825
Error/Critical Red #e94560
Info/Process Cyan #00d9ff
Muted/Future Gray #616161

Watermark

All diagrams include: arc-framework/cli

Mermaid Theme

%%{init: {'theme': 'dark'}}%%

Contributing

To add a new diagram:

  1. Create XX-diagram-name.md in this folder
  2. Include:
  • Title and description
  • Mermaid diagram code
  • Eraser.io prompt
  • Key files table
  • Watermark
  1. Add entry to this README
  2. Update VOTING.md if tracking

Generated: 2024-12-29 | Watermark: arc-framework/cli