GovAI Architecture Overview

GovAI is an evidence-first governance layer for AI systems.

System components

Edge

Governance clients

SDK, CLI, GitHub Action, customer CI.

Core

Audit HTTP API

Rust aigov_audit — evidence, compliance-summary, export.

Storage

Audit ledger

Append-only hash chain in Postgres or file ledger.

Evaluation

Policy engine

policy_version drives VALID / INVALID / BLOCKED.

Enterprise

Dashboard

Next.js operator UI, JWT routes, docs/help surfaces.

Read APIs

Functions 2.0

Flight pack, executive summary — not a second verdict.

The platform focuses on:

• decision-level auditability
• fail-closed enforcement
• evidence continuity
• operational governance enforcement

High-level architecture#

GovAI consists of several major layers:

1. Governance clients
2. CI/CD integrations
3. Runtime governance APIs
4. Audit ledger and evidence storage
5. Policy evaluation and enforcement
6. Evidence export and replay

Runtime governance

Live inference guarded by policy before side effects execute.

Pause

1. 1RequestRuntime evaluate call
2. 2PolicyModule evaluation
3. 3LedgerDecision trace optional
4. 4Allow / denyFail-closed on BLOCKED

Core concepts#

Decision-centric enforcement#

GovAI evaluates whether a system decision is governable and auditable.

The system does not only evaluate model quality. It evaluates whether:

• required evidence exists
• evaluations completed
• approvals are present
• traceability is intact
• integrity guarantees hold

Fail-closed semantics#

GovAI uses three primary verdicts:

• VALID
• INVALID
• BLOCKED

Missing governance evidence produces BLOCKED rather than implicit success.

Evidence continuity#

Audit records must remain linked to exported artifacts through deterministic or cryptographic integrity mechanisms.

Main components#

Python SDK#

The Python SDK provides:

• CLI workflows
• evidence export
• replay tooling
• CI integration helpers
• compliance verification tooling

Rust audit service#

The Rust service provides:

• governance APIs
• audit ingestion
• runtime evaluation
• evidence verification
• tenant isolation
• readiness and operational endpoints

Policy engine#

The policy layer evaluates:

• governance requirements
• enforcement rules
• approval requirements
• runtime governance constraints

CI/CD integration layer#

GovAI integrates into CI/CD pipelines using:

• GitHub Actions
• evidence bundle verification
• compliance gates
• replay validation

Runtime governance#

Runtime governance allows operational enforcement after deployment.

Examples:

• runtime blocking
• approval validation
• policy checks
• evidence validation
• runtime traceability

Tenant isolation#

Tenant isolation is derived from server-side API key mapping.

Headers are metadata only and are not security boundaries.

Deployment model#

Typical deployments include:

• local development
• self-hosted audit services
• hosted governance endpoints
• CI-integrated enforcement flows

Developer onboarding (diagram)#

For a single-page view from clone through runtime evaluate, evidence packs, CI gates, and hosted audit URLs, see developer_onboarding_flow.md.

HTTP surface (where to read more)#

The Rust binary exposes core metadata (GET /health, GET /status, …), readiness (GET /ready), and gated ledger routes (POST /evidence, GET /compliance-summary, GET /bundle-hash, GET /api/export/:run_id, billing, usage, …). A concise table lives in ARCHITECTURE.md; normative schemas and stability tags are in api/govai-http-v1.openapi.yaml. A reader summary is in api-reference.md.

Dashboard and enterprise APIs (Supabase JWT, assessments, compliance workflow queues) share the same deployment in many setups but use different auth from audit API keys—see ARCHITECTURE and OpenAPI Enterprise tags.

Shipped vs planned (high level)#

Future directions#

See roadmap.md for the public roadmap. Architecture themes called out there include deeper runtime governance, evidence UX, and standards/interoperability—without diluting fail-closed semantics.