USM

Universal System Map — a structured source of truth for agentic systems. A single .usm/ directory describes apps, services, features, flows, contracts, and decisions in YAML validated by a JSON Schema, and generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.

Identity

Quick Stats

App Services

Shared Services

Packages

• USM CLI
• USM MCP Server

Platform-Level

• Risks
• Roadmap
• Data Models
• Shared Patterns

Architecture Principles

TOGAF-style principles that govern all architecture decisions.

1. Structured Source of Truth (structured-source-of-truth)

Statement: Every system artifact is captured in YAML validated by a JSON Schema — no scattered, stale docs.

Rationale: Agents and humans need a single, machine-checkable source. Free-form docs drift; schema-validated YAML stays consistent.

Implications:

• All system descriptions must live in .usm/ YAML files
• The v1 JSON Schema is the contract — no undocumented fields

2. Agent First (agent-first)

Statement: USM files are designed for AI agent consumption via MCP tools before human readability.

Rationale: The MCP server exposes 8 tools that let agents navigate, search, and reference USM data without reading raw YAML.

Implications:

• Every .usm field must be parseable and queryable by agents
• The MCP server must stay in sync with the schema

3. Idempotent Generation (idempotent-generation)

Statement: Scan and generate are safe to run repeatedly; smart-merge preserves human edits.

Rationale: Re-running usm scan or usm generate should never destroy hand-written content. The smart-merge strategy preserves human-edited fields and updates mechanical ones.

Implications:

• Smart-merge distinguishes human-edited from scan-derived fields
• --force bypasses merge for intentional overwrite

4. One Source, Many Outputs (one-source-many-outputs)

Statement: A single .usm/ directory generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.

Rationale: Maintaining 6+ doc formats independently is unsustainable. Derive all from one source so they stay in sync.

Implications:

• Generators must read .usm files — never write docs from other docs
• Each generator is independent and composable