SARA

SARA stands for Solution Architecture Requirement for Alignment.

SARA is a command-line tool that manages Architecture documents and Requirements as an interconnected knowledge graph, providing a single source of truth for all teams and contributors in your organization.

Table of Contents

Expand contents

• Table of Contents
• Why SARA?
• Alignment Across Teams
• Markdown-First: A Radical Choice
• Features
• Installation
• From crates.io (Recommended)
• From Source
• Quick Start
• Commands
• Output Formats
• Configuration
• Environment Variables
• Document Types
• Traceability Hierarchy
• Relationships: The Heart of SARA
• Relationship Types
• Defining Relationships in YAML
• Peer Dependencies
• Architecture Decision Records
• Bidirectional Traceability
• Relationship Fields by Item Type
• Querying Relationships
• Validation Rules
• Custom Model Schema
• Declaring Item Types
• Field Types
• Declaring Relations
• Custom Document Templates
• Contributing
• License

Why SARA?

Alignment Across Teams

In complex organizations, requirements and architecture documents are often scattered across teams, tools, and repositories. SARA brings everyone together by creating a unified knowledge graph that ensures:

• Traceability: Every requirement traces back to business needs and forward to implementation
• Consistency: All teams work from the same source of truth
• Visibility: Stakeholders can see the complete picture, from solution vision to detailed design

Markdown-First: A Radical Choice

SARA deliberately uses plain Markdown files with YAML frontmatter instead of proprietary formats. This is a conscious decision:

• No vendor lock-in: Your requirements live in plain text files you own forever
• Universal readability: Anyone can read and edit documents without special software
• Developer-friendly: Markdown is the lingua franca of technical documentation
• Git-native: Full version control, branching, merging, and code review workflows
• AI-ready: Plain text formats are ideal for AI agents and LLMs - your requirements can be easily parsed, analyzed, and used as context for automated workflows and intelligent assistants
• Future-proof: Switch tools anytime - your data remains accessible
• Zero dependencies: No databases, no servers, no subscriptions
• DRY principle: Reuse your existing documentation - architecture diagrams, solution presentations, and product pages become part of your knowledge graph without duplication

Your requirements are too important to be trapped in a proprietary system. And your documentation should work harder - write once, trace everywhere.

Features

• Multi-Repository Support - Aggregate documents from multiple Git repositories into a unified graph
• Validation - Detect broken references, orphaned items, circular dependencies, and duplicate identifiers
• Traceability Queries - Traverse upstream (toward Solution) or downstream (toward Detailed Designs)
• Coverage Reports - Generate traceability matrices and coverage reports in multiple formats
• Version Comparison - Compare knowledge graphs between Git commits or branches
• Document Initialization - Generate YAML frontmatter templates for new documents
• Custom Model Schema - Define your own document types, fields and relations in YAML, without recompiling

Installation

From crates.io (Recommended)

cargo install sara-cli

From Source

# Clone the repository
git clone https://github.com/cledouarec/sara.git
cd sara

# Build and install
cargo install --path sara-cli

# Verify installation
sara --version

Quick Start

Commands

Output Formats

Most commands support multiple output formats:

# Text output (default)
sara report coverage

# JSON output
sara report coverage --format json

# CSV output
sara report matrix --format csv -o matrix.csv

Configuration

Sara uses a TOML configuration file (sara.toml by default):

# Optional: YAML file defining a custom domain model
model_schema = "model.yaml"

[repositories]
paths = [
    "./docs",
    "../other-repo/specs"
]

[validation]
strict_mode = false  # Enable strict validation (non-critical issues become errors)

[output]
colors = true
emojis = true

[templates]
paths = ["./templates"]  # Custom template directories (.tera document overrides)

Environment Variables

Document Types

Out of the box, Sara recognizes 10 document types forming a requirements hierarchy. They are the built-in default of a fully data-driven model: you can extend or redefine them with a custom model schema.

Traceability Hierarchy

erDiagram
    Solution {
        string id PK
        string name
        string description
    }

    UseCase {
        string id PK
        string name
        string description
        string[] refines FK
    }

    Scenario {
        string id PK
        string name
        string description
        string[] refines FK
    }

    SystemRequirement {
        string id PK
        string name
        string description
        string specification
        string[] derives_from FK
        string[] depends_on FK
    }

    SystemArchitecture {
        string id PK
        string name
        string description
        string platform
        string[] satisfies FK
    }

    HardwareRequirement {
        string id PK
        string name
        string description
        string specification
        string[] derives_from FK
        string[] depends_on FK
    }

    SoftwareRequirement {
        string id PK
        string name
        string description
        string specification
        string[] derives_from FK
        string[] depends_on FK
    }

    HardwareDetailedDesign {
        string id PK
        string name
        string description
        string[] satisfies FK
    }

    SoftwareDetailedDesign {
        string id PK
        string name
        string description
        string[] satisfies FK
    }

    ArchitectureDecisionRecord {
        string id PK
        string name
        string description
        string status
        string[] deciders
        string[] justifies FK
        string[] supersedes FK
    }

    Solution ||--o{ UseCase : "is_refined_by"
    UseCase ||--o{ Scenario : "is_refined_by"
    Scenario ||--o{ SystemRequirement : "derives"
    SystemRequirement ||--o{ SystemArchitecture : "is_satisfied_by"
    SystemArchitecture ||--o{ HardwareRequirement : "derives"
    SystemArchitecture ||--o{ SoftwareRequirement : "derives"
    HardwareRequirement ||--o{ HardwareDetailedDesign : "is_satisfied_by"
    SoftwareRequirement ||--o{ SoftwareDetailedDesign : "is_satisfied_by"
    SystemRequirement }o--o{ SystemRequirement : "depends_on"
    HardwareRequirement }o--o{ HardwareRequirement : "depends_on"
    SoftwareRequirement }o--o{ SoftwareRequirement : "depends_on"
    ArchitectureDecisionRecord ||--o{ SystemArchitecture : "justifies"
    ArchitectureDecisionRecord ||--o{ SoftwareDetailedDesign : "justifies"
    ArchitectureDecisionRecord ||--o{ HardwareDetailedDesign : "justifies"
    ArchitectureDecisionRecord }o--o{ ArchitectureDecisionRecord : "supersedes"

Relationships: The Heart of SARA

Relationships are what transform isolated documents into a connected knowledge graph. They establish traceability between items, enabling impact analysis, coverage tracking, and requirement validation.

Relationship Types

SARA uses semantic relationship names that reflect the nature of the connection:

Defining Relationships in YAML

Relationships are defined in the YAML frontmatter using reference fields:

---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
# Upstream: where this requirement comes from
derives_from:
  - "SCEN-001"
  - "SCEN-002"
# Downstream: what implements this requirement
is_satisfied_by:
  - "SYSARCH-001"
# Peer: dependencies on other requirements of the same type
depends_on:
  - "SYSREQ-002"  # Must have session management before auth timing
---

Peer Dependencies

Requirements can depend on other requirements of the same type using depends_on / is_required_by. This is useful for:

• Prerequisite requirements: SYSREQ-AUTH depends on SYSREQ-SESSION
• Ordering constraints: HWREQ-POWER must be satisfied before HWREQ-CPU
• Shared foundations: Multiple SW requirements depend on SWREQ-LOGGING

---
id: "SWREQ-RETRY"
type: software_requirement
name: "Retry Logic with Exponential Backoff"
derives_from:
  - "SYSARCH-COMM"
depends_on:
  - "SWREQ-LOGGING"  # Retry events must be logged
  - "SWREQ-CONFIG"   # Retry params come from config
---

Architecture Decision Records

ADRs capture significant design decisions and link them to the artifacts they justify. They have a lifecycle status and track decision-makers:

---
id: "ADR-001"
type: architecture_decision_record
name: "Use JWT for Authentication"
status: accepted
deciders:
  - "Alice Smith"
  - "Bob Johnson"
# Design artifacts this decision justifies
justifies:
  - "SYSARCH-AUTH"
  - "SWDD-AUTH-SERVICE"
---

# Context

We need a stateless authentication mechanism for our microservices.

# Decision

Use JWT (JSON Web Tokens) for authentication between services.

# Consequences

- Stateless: no session storage needed
- Tokens can be validated without database lookup
- Must handle token expiration and refresh

When a decision is replaced, use supersedes to maintain the decision history:

---
id: "ADR-002"
type: architecture_decision_record
name: "Switch to OAuth 2.0 with JWT"
status: accepted
deciders:
  - "Alice Smith"
supersedes:
  - "ADR-001"  # This ADR replaces the previous auth decision
justifies:
  - "SYSARCH-AUTH"
  - "SWDD-AUTH-SERVICE"
---

Bidirectional Traceability

You only need to define the relationship in one direction - SARA automatically infers the reverse link:

```yaml

In SCEN-001.md - defines downstream link

id: "SCEN-001" derives: - "SYSREQ-001"

OR in SYSREQ-001.md - defines upstre