# kab5der4/grc-engine architecture

> Architecture diagram of the GitHub repository kab5der4/grc-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kab5der4/grc-engine
- Repository: https://github.com/kab5der4/grc-engine

## Overview

#### Purpose and entry points
GRC Engine is a prototype privacy-first GRC platform that derives compliance state from infrastructure, evaluates controls deterministically, and stores tamper-evident evidence. It has three executable surfaces: FastAPI service startup in `backend/server.py`, local policy-audit CLI in `backend/app.py`, and a React/Vite studio entered through `frontend/src/main.jsx` and `frontend/src/App.jsx`.

#### Presentation and client state
The React 19 frontend provides dashboard, scan, control, evidence, finding, integration, report, and settings views. Routing/UI composition is centralized in `frontend/src/App.jsx`; API access is isolated in `frontend/src/services/api.js`. It also supports a client-side demo mode through `frontend/src/store/demoStore.js` and fixture data under `frontend/src/data/demo/`, so the deployed UI can operate independently of a live backend.

#### API gateway, identity, and authorization
FastAPI exposes versioned REST endpoints through `backend/api/v1/router.py`, mounted by `backend/server.py`. Domain endpoints cover auth, assets, controls, evidence, findings, integrations, reports, and scans, for example `backend/api/v1/endpoints/auth.py`, `backend/api/v1/endpoints/scans.py`, and `backend/api/v1/endpoints/evidence.py`. Authentication, JWT handling, password security, and role/clearance enforcement sit at the API boundary in `backend/core/security.py` and dependency wiring in `backend/api/deps.py`.

#### Discovery and integration boundary
Infrastructure ingestion is abstracted behind connector contracts in `backend/connectors/base.py`. GitHub is the concrete external integration in `backend/connectors/github.py`, while `backend/connectors/mock_github.py` supplies a sandbox/test-compatible source. Scan endpoints orchestrate this boundary, keeping third-party credentials and vendor-specific payload acquisition outside the core evaluator.

#### Compliance evaluation pipeline
The main control flow is scan/discovery → normalized assets or configurations → deterministic control evaluation → persisted evidence/findings → report generation. `backend/audit_engine.py` implements rule-based audit evaluation rather than AI-driven pass/fail decisions. `backend/api/v1/endpoints/controls.py` and `backend/api/v1/endpoints/findings.py` expose resulting compliance state; `backend/report_generator.py` produces attestation/report artifacts. The separate CLI entry point in `backend/app.py` applies local policy-document auditing and report output.

#### Evidence and persistence
SQLAlchemy models define the system of record for organizations, integrations, assets, controls, scans, audit outcomes, evidence, and findings; core entities are represented in `backend/models/asset.py`, `backend/models/control.py`, and `backend/models/evidence.py`. Database lifecycle/configuration is in `backend/database.py`, with schema evolution via `backend/alembic/env.py` and `backend/alembic/versions/2c06ba88f2a1_initial_schema_baseline.py`. The intended runtime supports SQLite or PostgreSQL; evidence integrity uses SHA-256 hashing as a cryptographic ledger boundary.

#### Deployment and operational boundaries
The backend is Python/FastAPI with Uvicorn, Pydantic, SQLAlchemy, Alembic, JWT, bcrypt, and async SQLite/PostgreSQL support declared in `backend/requirements.txt`. The frontend is a Vite-built React application configured in `frontend/vite.config.js`; `vercel.json` indicates Vercel-oriented frontend deployment. CI and security automation are defined in `.github/workflows/ci.yml` and `.github/workflows/security.yml`. GitHub is the currently material external service; AWS/cloud telemetry is an architectural target rather than a connector visible in this tree.

Main entry points: [`backend/api/v1/router.py`](https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/router.py) (v1 REST Router), [`frontend/src/App.jsx`](https://github.com/kab5der4/grc-engine/blob/main/frontend/src/App.jsx) (React/Vite Studio), [`backend/audit_engine.py`](https://github.com/kab5der4/grc-engine/blob/main/backend/audit_engine.py) (Deterministic Audit Engine), [`backend/models/asset.py`](https://github.com/kab5der4/grc-engine/blob/main/backend/models/asset.py) (Compliance Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Studio"]
  node_web["React/Vite Studio<br/>web client<br/>[App.jsx]"]
  node_web_entry["Client Entry<br/>bootstrap<br/>[main.jsx]"]
  node_api_client["API Client<br/>client service<br/>[api.js]"]
  node_demo_store["Demo Mode<br/>client state<br/>[demoStore.js]"]
end

subgraph group_api["FastAPI Service"]
  node_server["Service Startup<br/>FastAPI host<br/>[server.py]"]
  node_router["v1 REST Router<br/>API router<br/>[router.py]"]
  node_identity{{"Identity &amp; Access<br/>auth boundary<br/>[security.py]"}}
  node_api_dependencies["Auth Dependencies<br/>dependency wiring<br/>[deps.py]"]
  node_scan_api["Scan Endpoints<br/>REST endpoint<br/>[scans.py]"]
  node_compliance_api["Compliance Endpoints<br/>REST endpoints<br/>[controls.py]"]
end

subgraph group_engine["Evaluation Pipeline"]
  node_connector_contract["Connector Contract<br/>integration abstraction<br/>[base.py]"]
  node_github_connector{{"GitHub Connector<br/>external integration<br/>[github.py]"}}
  node_audit_engine["Deterministic Audit Engine<br/>rule evaluator<br/>[audit_engine.py]"]
  node_reporting["Report Generator<br/>artifact generator"]
  node_policy_cli["Local Policy Audit CLI<br/>CLI entry point<br/>[app.py]"]
end

subgraph group_data["System of Record"]
  node_models["Compliance Models<br/>SQLAlchemy models<br/>[asset.py]"]
  node_evidence_ledger{{"Evidence Ledger<br/>integrity boundary<br/>[evidence.py]"}}
  node_database[("SQLite / PostgreSQL<br/>relational database<br/>[database.py]")]
  node_migrations["Schema Migrations<br/>Alembic migrations<br/>[env.py]"]
end

node_web_entry -->|"boots"| node_web
node_web -->|"uses"| node_api_client
node_web -.->|"offline state"| node_demo_store
node_api_client -->|"REST"| node_server
node_server -->|"mounts"| node_router
node_router -->|"protects routes"| node_identity
node_identity -->|"wired by"| node_api_dependencies
node_router -->|"routes"| node_scan_api
node_router -->|"routes"| node_compliance_api
node_scan_api -->|"discovers through"| node_connector_contract
node_connector_contract -->|"implemented by"| node_github_connector
node_github_connector -->|"normalized assets/config"| node_audit_engine
node_audit_engine -->|"persists outcomes"| node_models
node_audit_engine -->|"records evidence"| node_evidence_ledger
node_models -->|"mapped to"| node_database
node_evidence_ledger -->|"stored in"| node_database
node_migrations -->|"evolves schema"| node_database
node_compliance_api -->|"reads compliance state"| node_models
node_compliance_api -->|"serves evidence"| node_evidence_ledger
node_models -->|"compliance state"| node_reporting
node_reporting -.->|"report artifacts"| node_web
node_policy_cli -->|"local policy evaluation"| node_audit_engine
node_policy_cli -->|"outputs reports"| node_reporting

click node_web "https://github.com/kab5der4/grc-engine/blob/main/frontend/src/App.jsx"
click node_web_entry "https://github.com/kab5der4/grc-engine/blob/main/frontend/src/main.jsx"
click node_api_client "https://github.com/kab5der4/grc-engine/blob/main/frontend/src/services/api.js"
click node_demo_store "https://github.com/kab5der4/grc-engine/blob/main/frontend/src/store/demoStore.js"
click node_server "https://github.com/kab5der4/grc-engine/blob/main/backend/server.py"
click node_router "https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/router.py"
click node_identity "https://github.com/kab5der4/grc-engine/blob/main/backend/core/security.py"
click node_api_dependencies "https://github.com/kab5der4/grc-engine/blob/main/backend/api/deps.py"
click node_scan_api "https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/endpoints/scans.py"
click node_compliance_api "https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/endpoints/controls.py"
click node_connector_contract "https://github.com/kab5der4/grc-engine/blob/main/backend/connectors/base.py"
click node_github_connector "https://github.com/kab5der4/grc-engine/blob/main/backend/connectors/github.py"
click node_audit_engine "https://github.com/kab5der4/grc-engine/blob/main/backend/audit_engine.py"
click node_reporting "https://github.com/kab5der4/grc-engine/blob/main/backend/report_generator.py"
click node_policy_cli "https://github.com/kab5der4/grc-engine/blob/main/backend/app.py"
click node_models "https://github.com/kab5der4/grc-engine/blob/main/backend/models/asset.py"
click node_evidence_ledger "https://github.com/kab5der4/grc-engine/blob/main/backend/models/evidence.py"
click node_database "https://github.com/kab5der4/grc-engine/blob/main/backend/database.py"
click node_migrations "https://github.com/kab5der4/grc-engine/blob/main/backend/alembic/env.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_web_entry,node_api_client,node_demo_store toneBlue
class node_server,node_router,node_identity,node_api_dependencies,node_scan_api,node_compliance_api toneAmber
class node_connector_contract,node_github_connector,node_audit_engine,node_reporting,node_policy_cli toneMint
class node_models,node_evidence_ledger,node_database,node_migrations toneRose
```

## Components

### React Studio

Interactive GRC dashboard with an offline demo mode.

- [React/Vite Studio](https://github.com/kab5der4/grc-engine/blob/main/frontend/src/App.jsx): web client · Dashboard, scan, evidence, finding, integration, and report views. · `frontend/src/App.jsx`
- [Client Entry](https://github.com/kab5der4/grc-engine/blob/main/frontend/src/main.jsx): bootstrap · `frontend/src/main.jsx`
- [API Client](https://github.com/kab5der4/grc-engine/blob/main/frontend/src/services/api.js): client service · `frontend/src/services/api.js`
- [Demo Mode](https://github.com/kab5der4/grc-engine/blob/main/frontend/src/store/demoStore.js): client state · Allows the UI to operate without the API. · `frontend/src/store/demoStore.js`

### FastAPI Service

Authenticated REST gateway and compliance orchestration.

- [Service Startup](https://github.com/kab5der4/grc-engine/blob/main/backend/server.py): FastAPI host · Mounts the versioned API. · `backend/server.py`
- [v1 REST Router](https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/router.py): API router · Routes domain endpoints for GRC resources. · `backend/api/v1/router.py`
- [Identity & Access](https://github.com/kab5der4/grc-engine/blob/main/backend/core/security.py): auth boundary · JWT, password security, roles, and clearance enforcement. · `backend/core/security.py`
- [Auth Dependencies](https://github.com/kab5der4/grc-engine/blob/main/backend/api/deps.py): dependency wiring · `backend/api/deps.py`
- [Scan Endpoints](https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/endpoints/scans.py): REST endpoint · Orchestrates infrastructure discovery. · `backend/api/v1/endpoints/scans.py`
- [Compliance Endpoints](https://github.com/kab5der4/grc-engine/blob/main/backend/api/v1/endpoints/controls.py): REST endpoints · Exposes controls, findings, and evidence. · `backend/api/v1/endpoints/controls.py`

### Evaluation Pipeline

Discovery, deterministic evaluation, and reporting.

- [Connector Contract](https://github.com/kab5der4/grc-engine/blob/main/backend/connectors/base.py): integration abstraction · Keeps vendor acquisition outside the evaluator. · `backend/connectors/base.py`
- [GitHub Connector](https://github.com/kab5der4/grc-engine/blob/main/backend/connectors/github.py): external integration · Concrete infrastructure source; mock variant supports sandbox use. · `backend/connectors/github.py`
- [Deterministic Audit Engine](https://github.com/kab5der4/grc-engine/blob/main/backend/audit_engine.py): rule evaluator · Derives control outcomes without AI pass/fail decisions. · `backend/audit_engine.py`
- [Report Generator](https://github.com/kab5der4/grc-engine/blob/main/backend/report_generator.py): artifact generator · Produces attestation and report artifacts. · `backend/report_generator.py`
- [Local Policy Audit CLI](https://github.com/kab5der4/grc-engine/blob/main/backend/app.py): CLI entry point · Audits local policy documents and emits reports. · `backend/app.py`

### System of Record

Relational compliance state and tamper-evident evidence.

- [Compliance Models](https://github.com/kab5der4/grc-engine/blob/main/backend/models/asset.py): SQLAlchemy models · Organizations, integrations, assets, controls, scans, outcomes, evidence, and findings. · `backend/models/asset.py`
- [Evidence Ledger](https://github.com/kab5der4/grc-engine/blob/main/backend/models/evidence.py): integrity boundary · SHA-256 hashes make stored evidence tamper-evident. · `backend/models/evidence.py`
- [SQLite / PostgreSQL](https://github.com/kab5der4/grc-engine/blob/main/backend/database.py): relational database · System of record for compliance state. · `backend/database.py`
- [Schema Migrations](https://github.com/kab5der4/grc-engine/blob/main/backend/alembic/env.py): Alembic migrations · `backend/alembic/env.py`

## Connections

- Client Entry → React/Vite Studio: boots
- React/Vite Studio → API Client: uses
- React/Vite Studio → Demo Mode: offline state
- API Client → Service Startup: REST
- Service Startup → v1 REST Router: mounts
- v1 REST Router → Identity & Access: protects routes
- Identity & Access → Auth Dependencies: wired by
- v1 REST Router → Scan Endpoints: routes
- v1 REST Router → Compliance Endpoints: routes
- Scan Endpoints → Connector Contract: discovers through
- Connector Contract → GitHub Connector: implemented by
- GitHub Connector → Deterministic Audit Engine: normalized assets/config
- Deterministic Audit Engine → Compliance Models: persists outcomes
- Deterministic Audit Engine → Evidence Ledger: records evidence
- Compliance Models → SQLite / PostgreSQL: mapped to
- Evidence Ledger → SQLite / PostgreSQL: stored in
- Schema Migrations → SQLite / PostgreSQL: evolves schema
- Compliance Endpoints → Compliance Models: reads compliance state
- Compliance Endpoints → Evidence Ledger: serves evidence
- Compliance Models → Report Generator: compliance state
- Report Generator → React/Vite Studio: report artifacts
- Local Policy Audit CLI → Deterministic Audit Engine: local policy evaluation
- Local Policy Audit CLI → Report Generator: outputs reports