Production Deployment Guide — Deploy SysMARA to Production

Configure, deploy, and monitor SysMARA applications in production.

The SysmaraServer Class

SysMARA includes a minimal built-in HTTP server — the SysmaraServer class. It is not a full web framework like Express or Fastify; it is a lightweight server designed to expose your capabilities as HTTP endpoints while enforcing your system's policies and invariants at runtime.

import { SysmaraServer } from '@sysmara/core';

const server = new SysmaraServer({
  port: 3000,
  host: '0.0.0.0',
  logLevel: 'info'
});

Route Registration

Routes map HTTP endpoints to capabilities. When a request arrives, the server extracts the actor context, enforces applicable policies, runs the capability, and validates invariants.

server.register('POST', '/api/orders', 'CreateOrder');
server.register('GET', '/api/orders/:id', 'GetOrder');
server.register('DELETE', '/api/orders/:id', 'CancelOrder');

Actor Extraction

Every request in SysMARA has an actor — the user or system performing the action. The server extracts actor information from the request (typically from authentication headers or tokens) and passes it through the policy enforcement pipeline. Policies can then check whether the actor has the required role, permissions, or scope.

Error Handling

SysMARA provides a structured error hierarchy for consistent error handling across your application:

• SysmaraError — The base error class. All SysMARA errors extend this.
• ValidationError — Thrown when input validation fails (e.g., a required field is missing).
• PolicyError — Thrown when a policy check fails (e.g., the actor lacks the required role).
• InvariantError — Thrown when an invariant would be violated by the operation.

These errors carry structured information (error code, context, severity) that the server translates into appropriate HTTP responses.

Built-in Endpoints

Every SysmaraServer instance exposes two built-in endpoints that cannot be overridden:

Production Configuration

For production deployments, configure these settings in sysmara.config.yaml or via environment variables:

# sysmara.config.yaml
name: my-service
version: 1.0.0
port: 3000
host: 0.0.0.0
logLevel: warn          # Use 'warn' or 'error' in production
specDir: system
appDir: app
generatedDir: generated

Key Production Settings

• port — The port the server listens on. Default is 3000. Set this to match your deployment infrastructure.
• host — The network interface to bind to. Default is 0.0.0.0 (all interfaces). In containerized environments, keep this as-is. Behind a reverse proxy, you might bind to 127.0.0.1.
• logLevel — Controls verbosity. Use debug or info in development, warn or error in production to reduce noise.

Graceful Shutdown

The SysmaraServer handles process signals for graceful shutdown. When it receives SIGTERM or SIGINT, it stops accepting new connections, finishes processing in-flight requests, and then exits cleanly. This is essential for zero-downtime deployments in container orchestrators like Kubernetes.

Monitoring with Diagnostics

SysMARA's diagnostic system is not just a build-time tool — it can be used to monitor system health in production workflows. Run sysmara doctor to perform a comprehensive health check across nine sections:

1. Config — Validates sysmara.config.yaml is present and well-formed.
2. Spec directory — Ensures the spec directory exists and contains files.
3. Parsing — Checks that all spec files parse and validate correctly.
4. Cross-validation — Verifies all references between specs resolve.
5. Boundaries — Checks module boundary rules for violations.
6. Invariants — Validates invariant definitions and their entity references.
7. Diagnostics — Runs the full diagnostic rule set.
8. Orphans — Detects specs that are defined but never referenced.
9. Cycles — Checks for circular dependencies in the system graph.

# Run full health check
npx sysmara doctor

# Machine-readable output for monitoring scripts
npx sysmara doctor --json

CI/CD Integration

Integrate SysMARA into your deployment pipeline to catch issues before they reach production:

# CI pipeline stages
# 1. Validate specs
npx sysmara validate

# 2. Build graph and run diagnostics
npx sysmara build

# 3. Comprehensive health check
npx sysmara doctor

# 4. Run your application tests
npm test

# 5. Deploy (only if all above pass)

Use the --json flag in CI to parse results programmatically:

# Fail the build if any diagnostic errors are found
npx sysmara build --json | jq -e '.diagnostics | map(select(.severity == "error")) | length == 0'

Deployment Checklist

• All specs validate cleanly (sysmara validate passes).
• No diagnostic errors (sysmara build produces no errors).
• Doctor check passes all nine sections (sysmara doctor).
• Log level set to warn or error.
• Health check endpoint (/health) configured in your load balancer.
• Graceful shutdown signals are properly forwarded to the process.
• Generated artifacts (system-graph.json, system-map.json) are included in the deployment.