How grcengineering/gigachad-grc works
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: traefik.yml Traefik · app.module.ts Controls · shared Shared platform · docker-compose.yml Docker Compose
Components 22
Edge & UI
- Traefik · External routing boundary.
gateway/traefik.yml - React SPA · Module-oriented GRC user interface.
frontend/src/main.tsx - API client
frontend/src/lib/api.ts - Auth context · Holds authentication state and development login behavior.
frontend/src/contexts/AuthContext.tsx
GRC Services
- Controls · Core controls, evidence, integrations, workflows, jobs, and notifications service.
services/controls/src/app.module.ts - Frameworks · Manages compliance frameworks, assessments, mappings, and gaps.
services/frameworks/src/app.module.ts - Policies · Policy lifecycle boundary.
services/policies/src/app.module.ts - TPRM · Vendor risk and contract boundary.
services/tprm/src/app.module.ts - Trust · Questionnaire and trust-center boundary.
services/trust/src/app.module.ts - Audit · Audit execution and portal boundary.
Shared Platform
- Shared platform · Cross-service contracts, auth, cache, storage, secrets, resilience, and types.
services/shared - PostgreSQL · Shared relational state and Prisma schema.
services/shared/prisma/schema.prisma - Redis · Background job queue plus event, session, and cache support.
- RustFS object storage · Stores uploaded evidence and objects.
- Keycloak · JWT and RBAC identity boundary.
auth/realm-export.json
Automation & AI
- Collectors & scheduler · Schedules collectors against external SaaS and cloud systems.
services/controls/src/collectors/collectors.scheduler.ts - MCP servers · Dedicated evidence and AI-assistant tool servers.
mcp-servers/grc-evidence/src/index.ts - AI providers · External AI models behind a common interface.
services/controls/src/ai/providers/ai-provider.interface.ts
Deployment & Operations
- Docker Compose · Starts the platform services and infrastructure.
docker-compose.yml - Prometheus & Grafana · Platform metrics and dashboards.
monitoring/prometheus.yml - Helm deployment
- Terraform · Provisions AWS infrastructure and observability resources.
terraform/main.tf
Connections 36
- 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