Cognita GRC documentation

Quickstart

The fastest path to a running Cognita is the Docker compose stack. It boots Postgres, Mailhog, the Inngest dev server, and the Next.js app on a single command.

# The Cognita repository is private during the design-partner phase.
# Request access at [email protected]; you'll receive an invite that
# lets you clone the repo.
git clone [email protected]:<your-org>/cognitagrc.git
cd cognitagrc
docker compose up
# → http://localhost:3007 (app) · 8025 (Mailhog) · 8288 (Inngest)

On first start, the app applies npx prisma db push and runs the seed (Northwind Mutual demo org + 5 evidence rows). After that the data layer is real Postgres-backed; in-memory fallbacks only fire when DATABASE_URL is unset.

Production deploys: see Self-hosting for Vercel + Fly + Railway recipes.

Architecture

Cognita is a Next.js 15 App Router monolith over a Postgres + Inngest + S3 Object Lock substrate. Every authed surface reads through lib/data-source.ts which adapts between Prisma (when DATABASE_URL is set) and in-memory fixtures (when it isn't). Mutations go throughlib/persisted-ledger.ts which signs and chains every entry before persistence.

Connectors

Cognita ingests model + telemetry data through typed connectors. Each connector implements a small interface (test, listModels, pullTelemetry); credentials are envelope-encrypted at rest and webhook signatures are HMAC-verified.

Install via POST /api/connectors/install; rotate credentials by re-installing with the same (connectorId, workspaceId) tuple — the row is upserted in place.

AI Impact Assessments

Every model registered in the registry triggers an AIIA when its intended-use changes materially or its tier crosses a boundary (PRD §5.3). The risk engine tokenizes the intended-use string and matches it against EU AI Act Annex III + supporting articles; each clause becomes an answerable question in the stepper.

Sign-off captures actor, role, decision, IP, and timestamp into both the regular audit log AND the evidence chain. PDF export is hand-rolled (lib/pdf-text.ts) so the artifact can be vetted at the byte level.

# Open or refresh the AIIA for a model
curl -X GET https://app.cognitagrc.io/api/aiia/<modelId>

# Save answers (debounced PUT in the UI)
curl -X PUT https://app.cognitagrc.io/api/aiia/<aiiaId>/answers \
  -H 'x-csrf-token: <token>' -H 'Content-Type: application/json' \
  -d '{ "answers": { "Annex III §1(b)": { "state": "addressed", "note": "..." } } }'

# Sign as model owner
curl -X POST https://app.cognitagrc.io/api/aiia/<aiiaId>/sign \
  -H 'x-csrf-token: <token>' \
  -d '{ "role": "model-owner", "decision": "approved" }'

Evidence ledger

Every state transition that affects compliance posture is appended to a hash-chained, KMS-signed ledger. Hourly Inngest cron computes a Merkle root over the past hour's entries and commits it to the configured anchor backend (S3 Object Lock COMPLIANCE in production, in-memory in dev).

Auditors run the bundled CLI offline: node verify-ledger.mjs <dir> exits 0 only when every entry hashes correctly, every signature verifies, and the recomputed Merkle root matches the anchor.

Auditor sessions

External auditors get scoped, time-boxed credentials that don't see operator-only data. Their actions write to a parallel chain (auditor_audit_log) so the regular activity feed stays untainted.

# Owner mints a one-time redemption token
curl -X POST https://app.cognitagrc.io/api/auditor-sessions \
  -H 'x-csrf-token: <token>' \
  -d '{ "auditorName": "TÜV SÜD", "scope": { "framework": "iso42001" } }'
# → { redemptionToken: "<one-time>", session: { ... } }

# Auditor exchanges the token for a session cookie (CSRF-exempt; rate-limited)
curl -X POST https://app.cognitagrc.io/api/auditor-sessions/redeem \
  -d '{ "token": "<one-time>" }'

API reference

Selected endpoints — see source for the full list. Every mutating call requires a CSRF token; vendor webhooks are signature-authenticated instead.

Self-hosting

Cognita ships ready-to-deploy configs for Vercel, Fly.io, Railway, and any Docker host.

Required env at minimum: DATABASE_URL, CONNECTOR_KEY_MASTER (32 bytes base64), and either Clerk env keys or DEV_AUTH_BYPASS=1.