name: architecture-patterns description: Use when understanding how the system is structured, how agents/tools/middleware compose, or when making architectural decisions. Covers Mastra engine, agent composition, DI container, tool factories, middleware pipeline, and feature folder patterns. metadata: version: "1.0"

Architecture Patterns

Mastra Engine

The single entry point is src/engine/index.ts. It creates one Mastra instance that registers:

• Agents — all agents in a single agents object
• Storage — PostgresStore for workflow snapshots and agent state
• Observability — DefaultExporter with SensitiveDataFilter
• Logger — Pino via @mastra/loggers
• Server — port/host, API routes, middleware stack

export const mastra = new Mastra({
  agents,
  storage: getPostgresStore(),
  server: {
    port: config.port,
    host: config.host,
    apiRoutes: [...observabilityRoutes, ...creditRoutes, ...incidentRoutes, ...workspaceRoutes],
    middleware: [
      createRequestTracing(),
      securityHeaders(),
      rateLimiter,
      createAppMiddleware(getPostgresStore),
    ],
  },
});

Memory stores are pre-initialized at startup via Promise.all.

Agent Composition

Each agent file in src/engine/agents/ follows a consistent structure:

1. Import tools from engine/tools/ (grouped by domain)
2. Wrap tools with composable wrappers:
   • guardToolsForSchemaCompat() — schema compatibility guard
   • withCompactOutput() — compress tool output
   • withToonOutput() — format output with toon-format
3. Configure memory (optional) — @mastra/memory + PostgresStore
4. Define the agent with new Agent({ id, name, description, instructions, model, tools, ... })
5. Apply shared defaults via agentDefaults() which adds credit tracking (and tool step logging in dev)

Agent Configuration Constants (in shared.ts)

Model Selection

Agents use either config.agentModel (full model) or config.agentLightModel (lighter/cheaper). Use openrouterProvider() for OpenRouter-specific settings (max tokens, caching, reasoning effort).

Input/Output Processors

• unicodeNormalizer — strips control chars, collapses whitespace
• tokenLimiter(n) — truncates output to n tokens
• ToolSearchProcessor — enables dynamic tool discovery via search_tools/load_tool

Tool Patterns

Tools live in src/engine/tools/ organized by domain:

• api/ — createTool/createApiTool wraps Nixopus API SDK calls with Zod input/output schemas
• codebase/ — workspace analysis tools (read_file, list_directory, grep, search)
• deploy/ — deployment orchestration
• diagnostics/ — HTTP probes, health checks
• github/ — repository operations, PR creation
• shared/ — composable tool wrappers

Tool wrappers are applied as a pipeline: withToonOutput(withCompactOutput(guardToolsForSchemaCompat(tools))).

Runtime Skills

Operational knowledge lives in skills/<name>/SKILL.md with YAML frontmatter (name, description, metadata.version). Agents load skills dynamically via read_skill("skill-name") in their instructions.

Skills are reference material for agents — not code. They guide decision-making during deployments, diagnostics, and infrastructure operations.

Dependency Injection

Lightweight DI via rsdi in src/container.ts:

const container = new DIContainer()
  .add('config', () => cfg)
  .add('db', ({ config }) => getDb(config.databaseUrl))
  .add('cacheFactory', () => getCacheStoreFactory());

Singleton lifecycle: initContainer() creates once, getContainer() returns it, resetContainer() for testing.

Middleware Pipeline

Middleware functions in src/middleware/ are factory functions that return Hono-style handlers:

export function createAppMiddleware(getPostgresStore: () => PostgresStore) {
  return async (c: { req: ..., header: ..., get: ..., res: ... }, next: () => Promise<void>) => {
    // middleware logic
    await next();
  };
}

Pipeline order in the engine:

1. createRequestTracing() — request ID, timing
2. securityHeaders() — security response headers
3. rateLimiter — rate limiting per path
4. createAppMiddleware() — auth, credits, org context, agent stream logging

Feature Folders

Vertical slices in src/features/ group related routes and domain logic:

• credits/ — wallet management, agent credit tracking, routes
• workspace/ — S3 workspace support, routes
• incidents/ — incident management
• inference/ — LLM inference configuration

Each feature exports its routes, which are composed into server.apiRoutes in the engine.

Shutdown

Graceful shutdown in src/engine/index.ts handles SIGTERM/SIGINT:

1. Shutdown pub/sub bus
2. Evict SSH orchestrators
3. Close DB pools
4. Exit