Add architecture + design docs with domain model

[ric03uec]

Summary

Create architecture and design documentation for Clawrium, including a shared domain model to guide future features.

Goals

• Provide a clear mental model of the system
• Align future work with shared vocabulary and boundaries
• Reduce onboarding time for contributors

Requirements

• Architecture overview (components, data flow, deployment model)
• Domain model with key entities and relationships (Host, Claw, Registry, Instance, Fleet, etc.)
• Sequence diagrams for common flows (deploy, upgrade, backup, metrics collection)
• Data model section aligned with current storage (and future SQLite)
• Place docs under docs/ (or existing conventions)

Acceptance Criteria

• Docs are discoverable from README
• Domain model is referenced in new PRDs
• At least one diagram per major flow

Notes

• Keep diagrams text-based (Mermaid) for easy maintenance

[ric03uec]

Triage Decision: enhancement, planning

Documentation task with clear goals and acceptance criteria. Ready for planning.

---

Prompt Log

Stage: triage
Skill: /clm:triage
Timestamp: 2026-04-05T16:19:10Z
Model: z-ai/glm-5

Find and triage issues that don't have workflow labels.

[ric03uec]

Implementation Plan

Overview

Create comprehensive architecture and design documentation using Mermaid diagrams for visualizations. The documentation will establish a shared domain model and mental framework for Clawrium's architecture, focusing on three main areas:

1. Architecture overview - Component relationships, deployment model, data flow
2. Domain model - Core entities (Host, Agent/Claw, Registry, Provider, Fleet) and their relationships
3. Sequence diagrams - Key operational flows (deploy, upgrade, backup, metrics)

Files to Create

1. docs/architecture.md - High-level architecture document

   • System components (CLI, Ansible runner, Host manager, Agent lifecycle)
   • Deployment model (control node + remote hosts via SSH)
   • Data flow diagrams
   • Technology stack rationale

2. docs/domain-model.md - Domain model and key entities

   • Entity definitions (Host, Agent, Registry, Provider, Instance, Fleet)
   • Entity relationships (UML-style class diagram)
   • Data model alignment with current storage (hosts.json, providers.json)
   • Future SQLite migration considerations

3. docs/flows/ directory - Sequence diagrams for major operations

   • deploy.md - Agent installation flow
   • upgrade.md - Agent upgrade flow
   • backup.md - Backup and restore flow
   • onboard.md - Agent onboarding workflow
   • lifecycle.md - Start/stop/restart operations

Files to Modify

1. docs/index.md - Add links to new architecture docs

   • Add "Architecture" section after "Getting Started"
   • Link to architecture.md, domain-model.md, and flows/

2. README.md - Add reference to architecture docs

   • Update "Documentation" link to mention architecture section
   • Keep high-level, point readers to full docs

Steps

1. Create docs/architecture.md with:

   • Component diagram (Mermaid)
   • Deployment model diagram
   • Technology stack section
   • References to existing docs (host-preparation, agent-onboarding)

2. Create docs/domain-model.md with:

   • Entity relationship diagram (Mermaid class diagram)
   • Detailed entity descriptions
   • Data storage mapping (current JSON files)
   • Future state notes (SQLite migration path)

3. Create docs/flows/ directory and sequence diagrams:

   • Each flow as a separate markdown file
   • Mermaid sequence diagrams showing actor interactions
   • Link to relevant code modules (e.g., core/install.py, core/lifecycle.py)

4. Update docs/index.md:

   • Add "## Architecture" section after "Getting Started"
   • Link to architecture docs with brief descriptions

5. Update README.md:

   • Update documentation link text to mention architecture
   • Keep existing structure, minimal changes

Test Strategy

• Verify all Mermaid diagrams render correctly on GitHub
• Ensure navigation from README → docs/index.md → architecture docs works
• Check that domain model entities match current codebase
• Validate sequence diagrams align with actual code flows
• Run make lint to ensure no formatting issues

Subtasks

None - single task execution. All documentation can be created in one cohesive pass.

Key Considerations

• Use text-based Mermaid diagrams (per requirements)
• Keep diagrams simple and maintainable
• Reference actual code modules in docs
• Align terminology with existing codebase (use "Agent" and "Claw" interchangeably, document this)
• Document both current state (JSON files) and future state (SQLite)
• Make diagrams discoverable from README

---

Prompt Log

Stage: planning
Skill: /clm:plan-build
Timestamp: 2026-04-11T18:30:00Z
Model: claude-sonnet-4-5-20250929

/clm:plan-build 13

[ric03uec]

Closing Notes

Closing this issue as the core documentation needs have been addressed through other efforts:

• AGENTS.md - Contains architecture overview, key concepts, and development workflow
• docs/agent-onboarding.md - Agent installation and configuration flows
• docs/host-preparation.md - Host setup and requirements
• docs/index.md - Documentation entry point

The remaining items (detailed sequence diagrams, formal domain model UML) can be revisited if contributors need them. The current documentation provides sufficient context for development.