SysMARA is a TypeScript framework where system architecture is a formal, machine-readable graph — not scattered across code, comments, and tribal knowledge. AI agents read your specs, understand constraints, and make safe changes.
AI coding agents are powerful, but they operate blind. They can generate code, but they cannot reason about what a change will break, which invariants must hold, or which modules they should not touch.
Traditional frameworks — Express, NestJS, Rails, Django — were designed for human developers who carry the system's architecture in their heads. Decorators, middleware chains, and implicit conventions work when the person writing code already understands the system. AI agents do not have that context.
The result: AI-generated code that compiles but violates business rules, crosses module boundaries, breaks invariants, and requires constant human review to catch architectural mistakes.
SysMARA makes your architecture a formal artifact. Every entity, capability, policy, invariant, module boundary, and data flow is declared in YAML specs, validated with Zod schemas, and compiled into a typed system graph. There is nothing to guess. There is nothing hidden.
When an AI agent needs to add a capability, it reads the system graph, checks which entities are involved, which invariants must hold, which policies govern access, and which module boundaries it must respect. Before writing any code, it can generate a change plan with impact analysis and risk classification.
A formal directed graph of your system: entities, capabilities, modules, policies, invariants, and flows as typed nodes with typed edges. A queryable, traversable graph that AI agents use to understand your system before changing it.
Learn more →Reads your capability specs along with their entity, policy, and invariant bindings, then generates route handler stubs, test scaffolds, and capability metadata with SHA-256 checksums. Generated code is deterministic and regenerable.
Learn more →Before mutating code, generate a formal Change Plan: what changes, what's affected, what risk level, which invariants are at stake, and whether human review is required. AI agents plan changes before making them.
Learn more →Domain objects with typed fields, constraints, and module assignments. The nouns of your system.
Named operations with typed inputs/outputs, entity bindings, policy gates, and invariant checks. The verbs.
Access control rules with actor conditions, priority ordering, and allow/deny effects.
Business rules that must hold. Bound to entities and capabilities. Enforced at compile time, runtime, or both.
Boundary enforcement. Explicit allowed/forbidden dependencies. Cycle detection. Ownership of entities and capabilities.
File ownership: generated (don't touch), editable (your code), protected (needs review), human-review-only.
# system/entities.yaml
- name: subscription
description: A recurring billing subscription
module: billing
fields:
- name: plan_id
type: string
required: true
- name: status
type: string
required: true
constraints:
- type: enum
value: [active, paused, cancelled, past_due]
- name: current_period_end
type: datetime
required: true
invariants:
- cannot_downgrade_with_unpaid_invoices# system/capabilities.yaml
- name: cancel_subscription
description: Cancel an active subscription
module: billing
entities: [subscription, invoice]
input:
- name: subscription_id
type: string
required: true
- name: reason
type: string
required: false
output:
- name: subscription
type: object
required: true
policies: [billing_admin, owner_transfer]
invariants: [cannot_downgrade_with_unpaid_invoices]
sideEffects: [send_cancellation_email, prorate_final_invoice]$ sysmara validate
[OK] Parsed 4 entities, 14 capabilities, 5 policies, 8 invariants, 3 modules, 3 flows
$ sysmara impact entity subscription
Target: entity:subscription
Affected modules: billing, workspaces
Affected capabilities: cancel_subscription, upgrade_subscription, downgrade_subscription
Affected invariants: cannot_downgrade_with_unpaid_invoices
Impact radius: 12 nodes
$ sysmara plan create "Add team billing"
[OK] Change plan written to .framework/plans/plan-a1b2c3d4e5f6.yaml
Risk: medium | Affected nodes: 8 | Human review: yesUsers, workspaces, subscriptions, invoices. Includes a sample change plan for adding team billing.
Multi-step approval workflows with audit trails and human-review-only safe edit zones.
Article lifecycle state machine, media assets, moderation policies.
SysMARA is open source, MIT licensed, and designed for teams building with AI agents.