Documentation/Architecture

Runtime architecture#

This document describes the code that exists today. Target product decisions are recorded in ADR 0001, and their implementation order is tracked in the development roadmap.

For the caller-facing model and reading paths, see core concepts and the documentation index. The README diagram includes planned components; the getting-started diagram shows the implemented evaluation loop.

The core evaluation model is scenario-independent. A caller supplies its Scene, policy and JSON evaluation context, evaluators submit checks and evidence, and the caller consumes the recorded decision. Production delivery and recovery are the first reference integrations.

Runtime#

cmd/open-guardrail delegates to internal/servercmd, which parses startup flags and creates a signal-aware context. internal/config loads strict YAML and environment settings. internal/bootstrap connects storage, applies or verifies migrations according to the configured mode, then opens the HTTP listener. internal/adapters/httpapi implements the generated standard-library HTTP server interface and serves diagnostics, identity APIs, OpenAPI and embedded assets. cmd/guardrailctl delegates to internal/ctlcmd, which communicates only over HTTP.

api/openapi/openapi.yaml is the source for public HTTP models, route interfaces and the Go client. Generated code is committed and checked for drift. The generated router does not replace authorization or complete request validation: the HTTP adapter retains the origin, CSRF, credential, body-size and unknown-field checks. Request bodies must be UTF-8 JSON objects with unique keys at every nesting level; duplicate keys, including escaped spellings of the same key, are rejected before application commands run. The outer HTTP middleware generates an opaque trace identifier for every response; error envelopes repeat it without returning internal error details.

Storage initialization has a 30-second deadline; readiness queries have a two-second deadline. SIGINT/SIGTERM allow ten seconds to drain HTTP requests before storage closes. A listener opens only after the database schema is ready.

Storage#

The application selects exactly one backend. internal/adapters/storage/sqlite uses a pure-Go driver, WAL, foreign keys and a bounded busy timeout. internal/adapters/storage/postgres uses pgx through database/sql with a bounded pool. internal/adapters/storage owns lifecycle and Goose migrations embedded from migrations/sqlite or migrations/postgres. Compiled-in extensions register a connection factory, migration filesystem, dialect and conflict handling through storage/driver. The shared repositories depend on these operations rather than on a particular extension or its third-party driver.

Built-in persistence infrastructure lives under internal/adapters/storage. Its explicit driver registry selects the backend and records its migration dialect, support level and current multi-instance guarantee. It provides separate connection entrypoints for startup and maintenance of existing databases. The root package manages migrations/readiness and implements shared identity and Spec repository SQL. Backend subpackages own database-specific connections and dialect behavior. Keep portable repository SQL shared; isolate backend-specific operations only where their behavior differs. Repository and transaction interfaces belong with the application use cases that consume them. Domain and application packages must not import storage adapters.

The initial schema creates all 15 business tables, including identity, Policy, Revision, Run, Submission, Evidence and scoped credentials. Final results and decisions are fields on Run. Each database has one initialization script; automatic migrations record their execution history.

With database.migrations: auto, startup installs the bundled schema. With external, the business schema must already exist. See database initialization.

The current preview supports one service instance per database. PostgreSQL multi-instance coordination and SQLite business-write contention must be verified as those features are introduced. A single SQLite connection reduces local contention; future business correctness must still come from transactions, conditional writes and constraints. The public capability response therefore reports multiInstance: false for all current adapters. It exposes only support level and the verified operating envelope, never the selected driver, connection string, file path or database topology.

The accepted v0.1 target keeps the backend configurable: SQLite is official for local/single-instance deployments and PostgreSQL is official for shared/multi-instance deployments. Both must preserve identical domain behavior through driver-specific implementations and a shared conformance suite. Additional drivers use the same ports and can enter a compatibility promise only after passing the suite. No driver selection may silently fall back to SQLite.

Deliberate scope#

The UI is embedded static management pages with no frontend build requirement. Future composition and provider directories contain design READMEs only; they do not define supported Go APIs or add runtime behavior. See the package layout. The current scope includes local administrator bootstrap and sessions; see the administrator guide. Scene settings live in scene; Policy metadata lives in policy. Both editable Drafts and published content live in policy_revision. internal/domain/spec owns document validation, canonical JSON and the digest. Drafts may be saved before validation; publishing validates and freezes a Revision. Activation is a separate compare-and-swap update. Draft edits update the same Revision row with last-write-wins semantics. See ADR 0002 for keys, constraints and initialization.

internal/application/spec.Service validates and canonicalizes documents and prepares the request identity for Scene initialization and Revision publication. HTTP handlers call this service. The storage port accepts prepared commands and retains project/Scene/Policy lock ordering, exact reviewed-Draft comparisons, idempotent replay checks and atomic audit writes. Validation no longer requires holding database write locks. Publication timestamps are still sampled after the required persistence locks through a deferred application clock.

The runtime API creates a Run from sceneKey and an arbitrary JSON object changeSet. Machine roles are issuance templates; each key persists its complete effective scopes and endpoint authorization checks those scopes. A Project-scoped RUN_ORCHESTRATOR key receives runs:create, runs:read and submission-credential:rotate. A trusted integration key may additionally receive runs:create-with-revision so it can select an immutable Revision already frozen by an upstream system. Ordinary orchestrator keys select through exact resource bindings, or use the Scene default active Revision when no resources are bound. A separate POLICY_PUBLISHER key receives policies:create and revisions:publish; it cannot create Runs or edit an administrator's Draft. The selected Policy Revision and Scene TTL are frozen in the Run with its policyId, policyRevisionId, Spec digest and normalized ChangeSet. A Run starts OPEN and creation returns its plaintext Submission Credential once; only a digest is persisted. A Project key can rotate the credential while OPEN. The matching Run credential submits complete Snapshots with a baseline number. Intermediate Snapshots advance the baseline. A final Snapshot atomically creates one Result and Decision and moves the Run to FINISHED. An overdue unfinished Run moves to EXPIRED. A finished Run retains its terminal state. The Policy Revision contains the immutable YAML and canonical Spec, so the Run does not copy them.

The identity application layer owns actual initialization and login use cases. It also owns Project-key lifetime and transition rules. Key creation defaults to 90 days; rotation preserves the existing expiry unless explicitly changed. Administrator sessions are rechecked in the same identity transaction as key issuance, version-checked rotation or idempotent revocation and their audit writes. Metadata pages never contain secrets or stored hashes. Authentication samples time after database reads, so pool waits do not extend a credential's lifetime. The current bootstrap and HTTP handlers still depend on the local identity service. Public enterprise composition and replaceable identity remain planned, as documented in the directory READMEs. No internal platform dependency, provider credential, private endpoint or telemetry is built into this service. Public APIs are documented by api/openapi/openapi.yaml.

Build choices#

The public module path is github.com/alibaba/open-guardrail, matching the canonical source repository. This module identity does not make the planned server-composition or provider interfaces supported Go APIs.

The release matrix currently includes Linux/macOS amd64/arm64. Both commands build with CGO disabled. PostgreSQL 17 is the shared-backend integration-test baseline. Docker is an optional packaging tool; extracted binaries run directly on the host.

The code uses Go 1.27.4, /livez for process liveness and minimal /readyz for dependency readiness. Anonymous version/capability discovery excludes commit hashes and dependency details.

Request execution budget#

HTTP handlers receive a 10-second context deadline, within the server's 15-second socket read/write timeouts. Repository calls pass that context to database/sql, bounding connection-pool and row-lock waits. An earlier client cancellation/deadline is preserved. Cancellation is cooperative: a handler does not run in a detached goroutine, and writes retain their existing atomic transaction and idempotent retry behavior. Storage cancellation maps to the existing unavailable response; callers should retry writes with the same key when the outcome is uncertain.

Continuous integration#

The repository workflow runs the shared test suite against disposable PostgreSQL, alongside SQLite, and checks the frontend, Python integrations, generated API client, dependency inventory and release archives. In a source checkout, the workflow is .github/workflows/ci.yaml. Native archives contain the development guide and release verification but do not include source-only CI configuration. Deployment-specific runner setup belongs in the integrating platform, outside the public source distribution.