Architecture Guide

Understand the project structure, build pipeline, and patterns for scaling your SysMARA project.

Project Structure

An SysMARA project has a well-defined directory layout. When you run sysmara init, it creates the foundational structure:

my-project/
  sysmara.config.yaml      # Project configuration
  system/                 # All spec files live here
    entities/             # Entity definitions
    capabilities/         # Capability definitions
    policies/             # Policy definitions
    invariants/           # Invariant definitions
    modules/              # Module boundary definitions
    flows/                # Multi-step flow definitions
  app/                    # Your application code
  generated/              # Generated artifacts (graph, map, compiled output)

The system/ directory is where all your declarative specs live. SysMARA reads everything in this directory to build its understanding of your system. The app/ directory is where your runtime application code goes. The generated/ directory contains artifacts produced by the build pipeline.

Configuration

The sysmara.config.yaml file controls how SysMARA operates. Here are all available fields:

name: my-project           # Project name
version: 0.1.0             # Project version
specDir: system             # Where spec files are located
appDir: app                 # Where application code lives
frameworkDir: .sysmara        # Internal framework directory
generatedDir: generated     # Where generated files go
port: 3000                  # Server port
host: 0.0.0.0              # Server host
logLevel: info              # Log level: debug, info, warn, error

All paths are relative to the project root. The defaults shown above are what sysmara init creates.

Spec File Organization

Each spec type has its own subdirectory under system/. Within each subdirectory, you have two organizational options:

Single File per Spec

The simplest approach. Each spec gets its own YAML file:

system/
  entities/
    user.yaml
    order.yaml
    product.yaml
  capabilities/
    create-order.yaml
    cancel-order.yaml

Directory of Files

For complex specs that benefit from grouping, you can use directories. SysMARA recursively reads all YAML files within each spec type directory:

system/
  entities/
    users/
      user.yaml
      user-profile.yaml
    orders/
      order.yaml
      order-item.yaml
  capabilities/
    users/
      register-user.yaml
      update-profile.yaml
    orders/
      create-order.yaml
      cancel-order.yaml

Both approaches work identically. SysMARA does not care about the file naming or nesting — it reads all .yaml files recursively and identifies spec types by their content.

How Specs Are Parsed

When SysMARA reads your spec files, it follows a three-step process:

  1. YAML parsing. Each file is parsed from YAML into a JavaScript object.
  2. Zod validation. The parsed object is validated against a Zod schema specific to that spec type. This ensures all required fields are present, types are correct, and values are within allowed ranges.
  3. SystemSpecs assembly. All validated specs are collected into a single SystemSpecs object that represents the complete system. This is the in-memory representation used by the rest of the pipeline.

If any file fails YAML parsing or Zod validation, the error is reported with the file path and specific validation failure. The pipeline does not continue past parsing errors.

The Build Pipeline

The sysmara build command runs the full pipeline in order:

  1. Parse. Read all spec files, validate with Zod, assemble into SystemSpecs.
  2. Validate. Cross-reference all specs. Check that capabilities reference real entities, policies reference real capabilities, modules contain only existing specs, and so on.
  3. Graph. Build the system graph — a directed graph of all relationships. Generate system-graph.json and system-map.json.
  4. Compile. Run the capability compiler, which processes capability specs into structured output the runtime can use.
  5. Diagnose. Run all diagnostic rules against the graph and specs. Produce diagnostic codes (AX101 through AX602) for any issues found.

Each step depends on the previous one succeeding. If parsing fails, validation does not run. If validation fails, the graph is not built.

You can run individual steps when needed:

# Just parse and validate
npx sysmara validate

# Just build the graph (includes validation)
npx sysmara graph

# Just run the compiler (requires valid graph)
npx sysmara compile

# Full pipeline
npx sysmara build

Module Organization for Large Systems

As your system grows beyond a handful of entities, modules become essential. A module groups related entities and capabilities together and defines boundary rules that control how modules interact.

Good module boundaries follow domain boundaries. If your system has billing, user management, and inventory, those are likely three modules:

module: billing
description: Handles subscriptions, invoices, and payments
entities:
  - Subscription
  - Invoice
  - Payment
capabilities:
  - CreateSubscription
  - CancelSubscription
  - ChargeInvoice
depends_on:
  - customers
forbidden_deps:
  - inventory

The depends_on field declares which other modules this module is allowed to depend on. The forbidden_deps field explicitly blocks dependencies that should never exist. SysMARA enforces these boundaries during validation and produces diagnostic codes (AX301-AX304) when violations are detected.

Signs Your Modules Need Restructuring

Explaining Your System

Use the sysmara explain command to get a human-readable description of any spec and its relationships:

# Explain a capability and what it connects to
npx sysmara explain capability CreateOrder

# Explain a module and its boundaries
npx sysmara explain module billing

# Explain an invariant and what it governs
npx sysmara explain invariant OrderTotalPositive

This is useful both for onboarding new developers and for feeding context to AI agents that need to understand a specific part of your system.