FAQ

Common questions and honest answers about what SysMARA is, what it does, and what it does not do.

Is SysMARA a web framework?

SysMARA includes a minimal built-in HTTP server (the SysmaraServer class), but it is not primarily a web framework. Its focus is on architecture specification and validation — defining your system's entities, capabilities, policies, invariants, and modules as declarative YAML specs, and then validating that those specs are consistent.

The built-in server provides basic route handling, actor extraction, and policy enforcement. It exposes a /health endpoint and a /_sysmara/routes endpoint for discovery. For applications that need more advanced HTTP features (middleware stacks, request parsing, WebSocket support), you can use SysMARA alongside a dedicated HTTP framework.

Does SysMARA replace Express, Fastify, or NestJS?

It can, for simple services. The built-in SysmaraServer handles basic HTTP routing and request handling. For many microservices, that is sufficient.

However, SysMARA and frameworks like Express or NestJS are solving different problems. SysMARA focuses on architectural correctness — ensuring your system's structure is sound, boundaries are respected, and invariants hold. Express and NestJS focus on HTTP request handling — middleware, routing, parsing, and response formatting.

You can use both together. Define your architecture in SysMARA specs, validate it with the CLI, and use Express or Fastify to handle HTTP concerns. SysMARA does not impose a specific HTTP framework.

What is the runtime overhead?

Minimal. SysMARA's primary work happens at build time, not runtime. The sysmara validate, sysmara build, and sysmara doctor commands run during development and CI/CD — they parse your specs, build graphs, and run diagnostics.

At runtime, the overhead consists of:

• Policy enforcement on incoming requests (checking actor permissions).
• Invariant validation when state changes occur.
• Route matching for registered endpoints.

These are lightweight operations. The framework does not add an ORM layer, query builder, or heavy abstraction on top of your application logic.

Can I use SysMARA without AI agents?

Yes. While SysMARA is designed to be AI-native — meaning its specs and outputs are structured for AI agent consumption — everything it produces is equally useful for human developers.

• Spec files are human-readable YAML that document your system's architecture.
• Diagnostic codes tell you exactly what is wrong and how to fix it.
• Impact analysis shows what will be affected before you make a change.
• The system map provides a clear inventory of your system's components.
• Change plans formalize your team's decision-making process.

AI agents benefit from these structured outputs, but they are not required. SysMARA works perfectly well as a pure architecture validation tool.

What databases does SysMARA support?

SysMARA is database-agnostic by design. It does not include a database driver, ORM, or query builder. Your entity specs define the logical structure of your domain objects — their fields, types, relationships, and constraints — but they do not prescribe how those objects are stored.

You choose your own database and data access layer. Use PostgreSQL with Prisma, MongoDB with Mongoose, DynamoDB with the AWS SDK, or anything else. SysMARA validates your architecture; your application code handles data persistence.

How does SysMARA handle authentication?

Through policies and actor context. Here is how it works:

1. When a request arrives, the SysmaraServer extracts actor information (typically from a JWT token or session).
2. The actor context is passed to the capability being invoked.
3. Policies attached to the capability check whether the actor meets the required conditions (e.g., has a specific role, is authenticated, has the right scope).
4. If any policy fails, the request is rejected with a PolicyError.

SysMARA does not provide a built-in authentication mechanism (no passport strategies, no JWT library). You implement authentication in your application code and expose the result as actor context. SysMARA then enforces authorization through policies.

Is SysMARA production-ready?

SysMARA is in early stage development. The core features — spec parsing, validation, diagnostics, graph generation, impact analysis, and change plans — are functional and tested. The API may change between versions as the framework matures.

What this means in practice:

• Safe to use for new projects where you control the upgrade path.
• Not yet recommended for large production systems that cannot tolerate API changes.
• Actively developed with regular releases and improvements.
• Pin your SysMARA version in package.json and test upgrades before deploying them.

How does SysMARA compare to GraphQL?

They are in entirely different categories. GraphQL is a query language and runtime for APIs — it defines how clients request data from servers. SysMARA is an architecture specification framework — it defines what your system's components are, how they relate, and what rules govern them.

You could use both in the same project — SysMARA to define and validate your architecture, GraphQL to define your API layer.

How do I handle migrations when specs change?

SysMARA does not manage database migrations. When you change an entity spec (add a field, rename a field, change a type), you need to handle the corresponding database migration yourself using your chosen migration tool (Prisma Migrate, Knex migrations, Flyway, etc.).

The recommended workflow is:

1. Run sysmara impact to understand what the change affects.
2. Create a change plan with sysmara plan create.
3. Update the spec file.
4. Run sysmara validate to check consistency.
5. Create and run the corresponding database migration.
6. Update application code as needed.

Can I use SysMARA with a monorepo?

Yes. Each service or package in your monorepo can have its own sysmara.config.yaml and system/ directory. Each one is validated independently. There is no built-in cross-service validation yet, but you can use the system map outputs from multiple services to build a composite view.

What language does SysMARA support?

SysMARA is written in TypeScript and runs on Node.js. Your spec files are YAML. Your application code is TypeScript or JavaScript. There are no official bindings for other languages at this time, though the spec format (YAML) and output formats (JSON) are language-agnostic.