kab5der4/grc-engine

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.