Architecture
as Code

A small language for describing software architecture. Not an implementation language — a compact way to record architectural intent so tooling can preserve it.

View on Codeberg Read the Spec
workspace.sar 
app Workspace {
    description "A system for creating and storing structured content"

    rule {
        "domains interact only through exposed interfaces and events"
    }

    check {
        "domain boundaries are enforced in generated code"
        "core behavior is covered by verification"
    }
}

domain Core {
    purpose "Own and evolve document state"

    own {
        concept Document
        concept Change
    }

    expose {
        interface Editing
        event DocumentChanged
    }
}

domain Storage {
    purpose "Persist and restore state"

    expose {
        interface Persistence
    }
}

Why Saurus?

Saurus is designed to answer the questions that matter when understanding a system. It records architectural intent in a machine-readable form so validators, generators, agents, and review tools can preserve it.

Structure What are the main parts of this system?
Ownership Which domain owns which concepts?
Exposure What does each domain expose to the rest of the system?
Verification Which constraints and obligations matter?

Building Blocks

app

Define the System

Use app to declare the system as a whole. Attach system-wide rules, invariants, and checks that apply everywhere.

domain

Architectural Boundaries

A good Saurus file has a small number of clear domain blocks. Each domain owns types, exposes interfaces and events, and states its purpose.

own / expose

Ownership and Contracts

own identifies concepts a domain is authoritative for. expose identifies what it makes available to the rest of the system.

rule / invariant

Constraints

rule states required constraints. invariant states properties the system is expected to uphold over time.

check

Verification Obligations

check states something that should be verified by tooling, tests, generated code, or review.

group / include

Composition and Reuse

group collects related declarations for reuse. include "path.sar" composes files into a single compilation unit.

Examples

Workspace System

app Workspace {
    description "A system for creating and storing structured content"

    rule {
        "domains interact only through exposed interfaces and events"
    }

    check {
        "domain boundaries are enforced in generated code"
    }
}

domain Core {
    purpose "Own and evolve document state"

    own {
        concept Document
        concept Change
    }

    expose {
        interface Editing
        event DocumentChanged
    }

    invariant {
        "reversing an applied change restores the prior state"
    }
}

domain Storage {
    purpose "Persist and restore state"

    expose {
        interface Persistence
    }

    check {
        "stored state can be restored without structural loss"
    }
}

Plugin Host

app PluginHost {
    description "A system for loading and isolating extensions"

    rule {
        "domains expose only intentional extension boundaries"
        "owned types are not modified outside their owning domain"
    }
}

domain Host {
    purpose "Load extensions and coordinate their lifecycle"

    own {
        concept PluginSession
    }

    expose {
        interface PluginBoundary {
            specification "./include/plugin_host.h"
        }
        event PluginLoaded
        event PluginUnloaded
    }

    rule {
        "plugins interact only through exposed interfaces and events"
    }
}

domain Isolation {
    purpose "Protect the host from plugin failures"

    expose {
        interface Enforcement
    }
}

Get Started

Install from Source

go install codeberg.org/saurus/saurus@latest

# Or clone and build
git clone https://codeberg.org/saurus/saurus.git
cd saurus
go build ./cmd/saurus

Usage

# Validate a .sar file
saurus validate path/to/file.sar

# Compile to normalized Markdown
saurus compile path/to/file.sar -o output.md

# Infer architecture from an existing project
saurus infer path/to/project -o inferred.sar

The normative language reference is in the specification. This page is the easier introduction.