# grcengineering/gigachad-grc architecture

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

- Interactive diagram: https://gitdiagram.com/grcengineering/gigachad-grc
- Repository: https://github.com/grcengineering/gigachad-grc

## Overview

#### Purpose and Runtime Entry Points
GigaChad GRC is a containerized enterprise governance, risk, and compliance platform. The normal local entry point is `start.sh` (or `start.bat`), which provisions environment secrets and starts Docker Compose. Service topology is defined in `docker-compose.yml`; production variants exist in `docker-compose.prod.yml`. The browser entry is the React SPA at `frontend/src/main.tsx`, rooted by `frontend/src/App.tsx`.

#### Edge, UI, and Request Routing
Traefik is the API gateway and external routing boundary, configured in `gateway/traefik.yml`. The Vite/React frontend provides module-oriented screens for controls, risk, audits, vendors, trust, and administration; authenticated API access is centralized through `frontend/src/lib/api.ts`. Authentication state and dev-login behavior are held in `frontend/src/contexts/AuthContext.tsx`. The frontend is deployed separately from APIs (`frontend/Dockerfile`) and communicates with backend service endpoints.

#### Domain Microservices
NestJS/TypeScript services separate major GRC domains, each with a `main.ts` bootstrap and an `app.module.ts` composition root:
- **Controls** is the core operational service: controls, evidence, risk, integrations, workflows, users, jobs, notifications, and BCDR. `services/controls/src/main.ts`, `services/controls/src/app.module.ts`, `services/controls/src/controls/controls.service.ts`.
- **Frameworks** manages compliance frameworks, assessments, mappings, gaps, and mapping suggestions. `services/frameworks/src/app.module.ts`, `services/frameworks/src/mappings/mappings.service.ts`.
- **Policies**, **TPRM**, **Trust**, and **Audit** isolate policy lifecycle, vendor risk/contracts, questionnaires/trust center, and audit execution/portal respectively. `services/policies/src/app.module.ts`, `services/tprm/src/app.module.ts`, `services/trust/src/app.module.ts`.

#### Core Compliance and Evidence Flow
Controls and frameworks establish the compliance model: framework catalogs and assessments map requirements to implemented controls; controls own evidence and implementation records. The frontend invokes service APIs; controllers validate and route to domain services; Prisma persists shared relational state. Evidence can originate from manual uploads or automated collectors, then feeds controls, audits, and reporting. Key paths: `services/controls/src/evidence/evidence.service.ts`, `services/controls/src/frameworks/catalog.service.ts`, `services/frameworks/src/mappings/mappings.service.ts`.

#### Automation, Integrations, and AI Boundary
The controls service manages third-party connection configuration, encrypted credentials, connector selection, scheduled collectors, and asynchronous jobs. Collectors call external systems such as AWS, GitHub, Okta, Azure, Google Workspace, and many SaaS/security tools. Redis-backed queueing supports background execution. MCP integration is mediated by controls, which manages MCP credentials/server configuration and invokes dedicated Node MCP servers. `services/controls/src/integrations/integrations.service.ts`, `services/controls/src/collectors/collectors.scheduler.ts`, `services/controls/src/mcp/mcp-client.service.ts`; MCP implementations include `mcp-servers/grc-evidence/src/index.ts` and `mcp-servers/grc-ai-assistant/src/index.ts`. AI providers are abstracted behind provider interfaces in `services/controls/src/ai/providers/ai-provider.interface.ts`.

#### Shared Platform Boundaries
`services/shared` supplies cross-service contracts and infrastructure adapters: Keycloak JWT/RBAC authorization, Redis event/session/cache support, S3-compatible storage, secrets providers, resilience, and shared types. It is the principal common dependency, rather than a separate business API. PostgreSQL is the system of record, with schema/migrations in `services/shared/prisma/schema.prisma` and database bootstrap SQL in `database/init/`. Keycloak realm initialization is under `auth/realm-export.json`.

#### Deployment and Operations
Docker Compose runs PostgreSQL, Redis, Keycloak, RustFS object storage, Traefik, frontend, and services. Prometheus/Grafana provide metrics and dashboards through `monitoring/prometheus.yml` and `monitoring/grafana/`. Helm templates support Kubernetes deployment (`helm/templates/`), while Terraform provisions AWS-oriented networking, ECS, RDS, Redis, S3, secrets, and observability (`terraform/main.tf`). Backup/restore and production operational scripts are in `deploy/`.

Main entry points: [`gateway/traefik.yml`](https://github.com/grcengineering/gigachad-grc/blob/main/gateway/traefik.yml) (Traefik), [`services/controls/src/app.module.ts`](https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/app.module.ts) (Controls), [`services/shared`](https://github.com/grcengineering/gigachad-grc/tree/main/services/shared) (Shared platform), [`docker-compose.yml`](https://github.com/grcengineering/gigachad-grc/blob/main/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge & UI"]
  node_traefik{{"Traefik<br/>API gateway<br/>[traefik.yml]"}}
  node_frontend["React SPA<br/>browser client<br/>[main.tsx]"]
  node_frontend_api["API client<br/>authenticated client<br/>[api.ts]"]
  node_auth_state["Auth context<br/>frontend auth<br/>[AuthContext.tsx]"]
end

subgraph group_domains["GRC Services"]
  node_controls["Controls<br/>NestJS domain service<br/>[app.module.ts]"]
  node_frameworks["Frameworks<br/>NestJS domain service<br/>[app.module.ts]"]
  node_policies["Policies<br/>NestJS domain service<br/>[app.module.ts]"]
  node_tprm["TPRM<br/>NestJS domain service<br/>[app.module.ts]"]
  node_trust["Trust<br/>NestJS domain service<br/>[app.module.ts]"]
  node_audit["Audit<br/>NestJS domain service"]
end

subgraph group_platform["Shared Platform"]
  node_shared["Shared platform<br/>shared library"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[schema.prisma]")]
  node_redis["Redis<br/>queue and cache"]
  node_object_storage[("RustFS object storage<br/>S3-compatible storage")]
  node_keycloak{{"Keycloak<br/>identity provider<br/>[realm-export.json]"}}
end

subgraph group_automation["Automation &amp; AI"]
  node_collectors["Collectors &amp; scheduler<br/>automation layer"]
  node_mcp["MCP servers<br/>Node AI tools<br/>[index.ts]"]
  node_ai_providers["AI providers<br/>provider abstraction"]
end

subgraph group_operations["Deployment &amp; Operations"]
  node_compose["Docker Compose<br/>runtime topology<br/>[docker-compose.yml]"]
  node_observability["Prometheus &amp; Grafana<br/>monitoring<br/>[prometheus.yml]"]
  node_helm["Helm deployment<br/>Kubernetes packaging"]
  node_terraform["Terraform<br/>AWS infrastructure<br/>[main.tf]"]
end

node_compose -->|"runs"| node_traefik
node_compose -->|"runs"| node_frontend
node_compose -->|"runs"| node_postgres
node_compose -->|"runs"| node_redis
node_compose -->|"runs"| node_keycloak
node_traefik -->|"routes browser traffic"| node_frontend
node_frontend -->|"uses"| node_auth_state
node_auth_state -->|"authenticates with"| node_keycloak
node_frontend -->|"uses"| node_frontend_api
node_frontend_api -->|"calls APIs through"| node_traefik
node_traefik -->|"routes API requests"| node_controls
node_traefik -->|"routes API requests"| node_frameworks
node_traefik -->|"routes API requests"| node_policies
node_traefik -->|"routes API requests"| node_tprm
node_traefik -->|"routes API requests"| node_trust
node_traefik -->|"routes API requests"| node_audit
node_controls -->|"maps controls to requirements"| node_frameworks
node_controls -->|"configures and schedules"| node_collectors
node_collectors -->|"queues background work"| node_redis
node_collectors -->|"returns collected evidence"| node_controls
node_controls -->|"invokes tools"| node_mcp
node_controls -->|"uses"| node_ai_providers
node_controls -->|"stores evidence"| node_object_storage
node_controls -->|"persists domain state"| node_postgres
node_frameworks -->|"persists assessments and mappings"| node_postgres
node_policies -->|"depends on"| node_shared
node_tprm -->|"depends on"| node_shared
node_trust -->|"depends on"| node_shared
node_audit -->|"depends on"| node_shared
node_shared -->|"provides JWT/RBAC adapter"| node_keycloak
node_shared -->|"provides cache and event adapters"| node_redis
node_shared -->|"provides storage adapter"| node_object_storage
node_shared -->|"provides Prisma access"| node_postgres
node_observability -.->|"monitors runtime"| node_compose
node_helm -.->|"production deployment alternative"| node_compose
node_terraform -->|"provisions deployment infrastructure"| node_helm

click node_compose "https://github.com/grcengineering/gigachad-grc/blob/main/docker-compose.yml"
click node_traefik "https://github.com/grcengineering/gigachad-grc/blob/main/gateway/traefik.yml"
click node_frontend "https://github.com/grcengineering/gigachad-grc/blob/main/frontend/src/main.tsx"
click node_frontend_api "https://github.com/grcengineering/gigachad-grc/blob/main/frontend/src/lib/api.ts"
click node_auth_state "https://github.com/grcengineering/gigachad-grc/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_controls "https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/app.module.ts"
click node_frameworks "https://github.com/grcengineering/gigachad-grc/blob/main/services/frameworks/src/app.module.ts"
click node_policies "https://github.com/grcengineering/gigachad-grc/blob/main/services/policies/src/app.module.ts"
click node_tprm "https://github.com/grcengineering/gigachad-grc/blob/main/services/tprm/src/app.module.ts"
click node_trust "https://github.com/grcengineering/gigachad-grc/blob/main/services/trust/src/app.module.ts"
click node_shared "https://github.com/grcengineering/gigachad-grc/tree/main/services/shared"
click node_postgres "https://github.com/grcengineering/gigachad-grc/blob/main/services/shared/prisma/schema.prisma"
click node_collectors "https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/collectors/collectors.scheduler.ts"
click node_mcp "https://github.com/grcengineering/gigachad-grc/blob/main/mcp-servers/grc-evidence/src/index.ts"
click node_ai_providers "https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/ai/providers/ai-provider.interface.ts"
click node_keycloak "https://github.com/grcengineering/gigachad-grc/blob/main/auth/realm-export.json"
click node_observability "https://github.com/grcengineering/gigachad-grc/blob/main/monitoring/prometheus.yml"
click node_terraform "https://github.com/grcengineering/gigachad-grc/blob/main/terraform/main.tf"

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_traefik,node_frontend,node_frontend_api,node_auth_state toneBlue
class node_controls,node_frameworks,node_policies,node_tprm,node_trust,node_audit toneAmber
class node_shared,node_postgres,node_redis,node_object_storage,node_keycloak toneMint
class node_collectors,node_mcp,node_ai_providers toneRose
class node_compose,node_observability,node_helm,node_terraform toneIndigo
```

## Components

### Edge & UI

- [Traefik](https://github.com/grcengineering/gigachad-grc/blob/main/gateway/traefik.yml): API gateway · External routing boundary. · `gateway/traefik.yml`
- [React SPA](https://github.com/grcengineering/gigachad-grc/blob/main/frontend/src/main.tsx): browser client · Module-oriented GRC user interface. · `frontend/src/main.tsx`
- [API client](https://github.com/grcengineering/gigachad-grc/blob/main/frontend/src/lib/api.ts): authenticated client · `frontend/src/lib/api.ts`
- [Auth context](https://github.com/grcengineering/gigachad-grc/blob/main/frontend/src/contexts/AuthContext.tsx): frontend auth · Holds authentication state and development login behavior. · `frontend/src/contexts/AuthContext.tsx`

### GRC Services

- [Controls](https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/app.module.ts): NestJS domain service · Core controls, evidence, integrations, workflows, jobs, and notifications service. · `services/controls/src/app.module.ts`
- [Frameworks](https://github.com/grcengineering/gigachad-grc/blob/main/services/frameworks/src/app.module.ts): NestJS domain service · Manages compliance frameworks, assessments, mappings, and gaps. · `services/frameworks/src/app.module.ts`
- [Policies](https://github.com/grcengineering/gigachad-grc/blob/main/services/policies/src/app.module.ts): NestJS domain service · Policy lifecycle boundary. · `services/policies/src/app.module.ts`
- [TPRM](https://github.com/grcengineering/gigachad-grc/blob/main/services/tprm/src/app.module.ts): NestJS domain service · Vendor risk and contract boundary. · `services/tprm/src/app.module.ts`
- [Trust](https://github.com/grcengineering/gigachad-grc/blob/main/services/trust/src/app.module.ts): NestJS domain service · Questionnaire and trust-center boundary. · `services/trust/src/app.module.ts`
- **Audit**: NestJS domain service · Audit execution and portal boundary.

### Shared Platform

- [Shared platform](https://github.com/grcengineering/gigachad-grc/tree/main/services/shared): shared library · Cross-service contracts, auth, cache, storage, secrets, resilience, and types. · `services/shared`
- [PostgreSQL](https://github.com/grcengineering/gigachad-grc/blob/main/services/shared/prisma/schema.prisma): system of record · Shared relational state and Prisma schema. · `services/shared/prisma/schema.prisma`
- **Redis**: queue and cache · Background job queue plus event, session, and cache support.
- **RustFS object storage**: S3-compatible storage · Stores uploaded evidence and objects.
- [Keycloak](https://github.com/grcengineering/gigachad-grc/blob/main/auth/realm-export.json): identity provider · JWT and RBAC identity boundary. · `auth/realm-export.json`

### Automation & AI

- [Collectors & scheduler](https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/collectors/collectors.scheduler.ts): automation layer · Schedules collectors against external SaaS and cloud systems. · `services/controls/src/collectors/collectors.scheduler.ts`
- [MCP servers](https://github.com/grcengineering/gigachad-grc/blob/main/mcp-servers/grc-evidence/src/index.ts): Node AI tools · Dedicated evidence and AI-assistant tool servers. · `mcp-servers/grc-evidence/src/index.ts`
- [AI providers](https://github.com/grcengineering/gigachad-grc/blob/main/services/controls/src/ai/providers/ai-provider.interface.ts): provider abstraction · External AI models behind a common interface. · `services/controls/src/ai/providers/ai-provider.interface.ts`

### Deployment & Operations

- [Docker Compose](https://github.com/grcengineering/gigachad-grc/blob/main/docker-compose.yml): runtime topology · Starts the platform services and infrastructure. · `docker-compose.yml`
- [Prometheus & Grafana](https://github.com/grcengineering/gigachad-grc/blob/main/monitoring/prometheus.yml): monitoring · Platform metrics and dashboards. · `monitoring/prometheus.yml`
- **Helm deployment**: Kubernetes packaging
- [Terraform](https://github.com/grcengineering/gigachad-grc/blob/main/terraform/main.tf): AWS infrastructure · Provisions AWS infrastructure and observability resources. · `terraform/main.tf`

## Connections

- Docker Compose → Traefik: runs
- Docker Compose → React SPA: runs
- Docker Compose → PostgreSQL: runs
- Docker Compose → Redis: runs
- Docker Compose → Keycloak: runs
- Traefik → React SPA: routes browser traffic
- React SPA → Auth context: uses
- Auth context → Keycloak: authenticates with
- React SPA → API client: uses
- API client → Traefik: calls APIs through
- Traefik → Controls: routes API requests
- Traefik → Frameworks: routes API requests
- Traefik → Policies: routes API requests
- Traefik → TPRM: routes API requests
- Traefik → Trust: routes API requests
- Traefik → Audit: routes API requests
- Controls → Frameworks: maps controls to requirements
- Controls → Collectors & scheduler: configures and schedules
- Collectors & scheduler → Redis: queues background work
- Collectors & scheduler → Controls: returns collected evidence
- Controls → MCP servers: invokes tools
- Controls → AI providers: uses
- Controls → RustFS object storage: stores evidence
- Controls → PostgreSQL: persists domain state
- Frameworks → PostgreSQL: persists assessments and mappings
- Policies → Shared platform: depends on
- TPRM → Shared platform: depends on
- Trust → Shared platform: depends on
- Audit → Shared platform: depends on
- Shared platform → Keycloak: provides JWT/RBAC adapter
- Shared platform → Redis: provides cache and event adapters
- Shared platform → RustFS object storage: provides storage adapter
- Shared platform → PostgreSQL: provides Prisma access
- Prometheus & Grafana → Docker Compose: monitors runtime
- Helm deployment → Docker Compose: production deployment alternative
- Terraform → Helm deployment: provisions deployment infrastructure