Architecture

SpendGuard AI separates domain truth from delivery mechanism. Every consequential effect flows through a canonical proposal, an independent approval bound to an exact version, idempotent durable execution, and an authoritative receipt — never directly from model text or tool arguments.

apps/web

Next.js App Router product: public marketing pages, authenticated product UI, the MCP HTTP transport, the AI chat host, and the durable workflow entry points.

services/risk-engine

An independently deployable Python MCP server that scores proposed savings actions and simulates commitment plans. It returns evidence; it never approves or executes.

packages/domain

Pure business logic: tenants, spend aggregation, anomaly detection, proposal validation, and state transitions. Imports nothing from Next.js, MCP, the database, or a model.

packages/contracts

Zod schemas and generated artifacts shared at every trust boundary between the UI, MCP tools, and the risk service.

packages/db

Drizzle schema, committed migrations, and repository adapters over Neon Postgres. Tenant ownership is explicit on every row.

packages/auth + policy

WorkOS-verified identity turned into an internal principal, and pure authorize() decisions with reason codes. Tenant, role, and scope always come from verified server context.

packages/mcp-server + mcp-host

The narrow, semantic MCP tool surface (list_cost_centers, detect_spend_anomalies, draft_savings_action, and so on) and the host-side router that connects the AI SDK chat experience to eligible tools.

packages/registry

A control-plane catalog that discovers, fingerprints, admits, and can quarantine MCP servers — including cross-runtime servers like the Python risk engine.

This page will grow with diagrams and the full dependency-direction map as the MCP server, host, and workflow layers are built out in later phases.