# dezign365/grc-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/dezign365/grc-copilot
- Repository: https://github.com/dezign365/grc-copilot

## Overview

GRC Copilot is a SaaS workspace for creating and reviewing IT governance, risk, and compliance materials, with framework guidance, AI assistance, and subscription management. The principal workflow is to provide requirements and framework context, generate or stream a policy/document, and review uploaded material for compliance gaps; a separate questionnaire flow can analyze spreadsheet requirements using existing policies as context. The graph includes major capabilities visible in the tree, but UI-to-API wiring and unsampled modules are not asserted where source evidence was unavailable.

Main entry points: [`src/app/api/generate/route.ts`](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/generate/route.ts) (Document generation), [`src/app/api/generate-stream/route.ts`](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/generate-stream/route.ts) (Stream generation), [`src/app/api/chat/route.ts`](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/chat/route.ts) (GRC chat), [`src/lib/usage.ts`](https://github.com/dezign365/grc-copilot/blob/main/src/lib/usage.ts) (Usage limits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Workspace"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_analyzer_ui["Compliance analyzer"]
  node_chat_ui["Chat workspace<br/>[page.tsx]"]
  node_frameworks_ui["Framework catalog<br/>[page.tsx]"]
  node_billing_ui["Billing dashboard"]
  node_admin_ui["Admin console<br/>[page.tsx]"]
end

subgraph group_intelligence["GRC Intelligence"]
  node_generate["Document generation<br/>[route.ts]"]
  node_stream_generate["Stream generation<br/>[route.ts]"]
  node_analyze["Document analysis<br/>[route.ts]"]
  node_questionnaire["Spreadsheet questionnaire<br/>[route.ts]"]
  node_brain["Question planning<br/>[route.ts]"]
  node_chat["GRC chat<br/>[route.ts]"]
  node_framework_data["Framework and control data"]
  node_prompt["GRC prompts"]
  node_fallback["LLM fallback<br/>[fallback-llm.ts]"]
end

subgraph group_account["Identity and Usage"]
  node_auth_callback["Auth callback<br/>[route.ts]"]
  node_usage["Usage limits<br/>[usage.ts]"]
end

subgraph group_billing["Plans and Billing"]
  node_checkout["Subscription checkout<br/>[route.ts]"]
  node_billing_portal["Billing portal<br/>[route.ts]"]
  node_stripe_webhook["Stripe webhook<br/>[route.ts]"]
  node_admin_packages["Package management<br/>[route.ts]"]
end

subgraph group_integrations["External Services"]
  node_supabase[("Supabase auth and data")]
  node_google_ai["Google Gemini"]
  node_other_ai["Other AI providers"]
  node_stripe["Stripe"]
  node_email_service["Email service<br/>[email.ts]"]
end

node_user(("GRC user"))

node_user -->|"uses"| node_dashboard
node_user -->|"submits document"| node_analyzer_ui
node_user -->|"asks questions"| node_chat_ui
node_user -->|"browses"| node_frameworks_ui
node_user -->|"manages plan"| node_billing_ui
node_user -->|"administers"| node_admin_ui
node_analyze -->|"authenticates and reads profile"| node_supabase
node_analyze -->|"checks and records usage"| node_usage
node_analyze -->|"validates and analyzes"| node_google_ai
node_questionnaire -->|"authenticates and reads policies"| node_supabase
node_questionnaire -->|"answers requirements"| node_google_ai
node_questionnaire -.->|"fallback answers"| node_other_ai
node_generate -->|"authenticates and reads context"| node_supabase
node_generate -->|"checks and records usage"| node_usage
node_generate -->|"uses prompt"| node_prompt
node_generate -->|"generates structured document"| node_google_ai
node_generate -.->|"fallback generation"| node_other_ai
node_stream_generate -->|"authenticates and reads profile"| node_supabase
node_stream_generate -->|"checks and records usage"| node_usage
node_stream_generate -->|"uses prompt"| node_prompt
node_stream_generate -->|"streams document"| node_google_ai
node_chat -->|"authenticates and reads profile"| node_supabase
node_chat -->|"checks and records usage"| node_usage
node_chat -->|"streams response"| node_google_ai
node_chat -.->|"fallback response"| node_other_ai
node_brain -->|"authenticates"| node_supabase
node_brain -->|"requests questions"| node_fallback
node_fallback -.->|"tries provider"| node_google_ai
node_fallback -.->|"tries fallback"| node_other_ai
node_auth_callback -->|"verifies session"| node_supabase
node_auth_callback -->|"sends welcome email"| node_email_service
node_checkout -->|"authenticates and reads package"| node_supabase
node_checkout -->|"creates checkout session"| node_stripe
node_billing_portal -->|"reads customer profile"| node_supabase
node_billing_portal -->|"creates portal session"| node_stripe
node_stripe_webhook -->|"retrieves subscription and invoice"| node_stripe
node_stripe_webhook -->|"updates billing records"| node_supabase
node_stripe_webhook -->|"sends payment email"| node_email_service
node_admin_packages -->|"checks admin and stores packages"| node_supabase
node_admin_packages -->|"syncs products and prices"| node_stripe

click node_dashboard "https://github.com/dezign365/grc-copilot/blob/main/src/app/dashboard/page.tsx"
click node_analyzer_ui "https://github.com/dezign365/grc-copilot/blob/main/src/app/dashboard/ComplianceAnalyzer.tsx"
click node_chat_ui "https://github.com/dezign365/grc-copilot/blob/main/src/app/chat/page.tsx"
click node_frameworks_ui "https://github.com/dezign365/grc-copilot/blob/main/src/app/frameworks/page.tsx"
click node_billing_ui "https://github.com/dezign365/grc-copilot/blob/main/src/components/BillingDashboard.tsx"
click node_admin_ui "https://github.com/dezign365/grc-copilot/blob/main/src/app/admin/page.tsx"
click node_generate "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/generate/route.ts"
click node_stream_generate "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/generate-stream/route.ts"
click node_analyze "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/analyze/route.ts"
click node_questionnaire "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/analyze/questionnaire/route.ts"
click node_brain "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/brain/route.ts"
click node_chat "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/chat/route.ts"
click node_framework_data "https://github.com/dezign365/grc-copilot/blob/main/src/lib/excellogFramework.ts"
click node_prompt "https://github.com/dezign365/grc-copilot/blob/main/src/lib/grc-system-prompt.ts"
click node_fallback "https://github.com/dezign365/grc-copilot/blob/main/src/lib/fallback-llm.ts"
click node_auth_callback "https://github.com/dezign365/grc-copilot/blob/main/src/app/auth/callback/route.ts"
click node_usage "https://github.com/dezign365/grc-copilot/blob/main/src/lib/usage.ts"
click node_checkout "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/checkout/route.ts"
click node_billing_portal "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/billing/route.ts"
click node_stripe_webhook "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/webhook/stripe/route.ts"
click node_admin_packages "https://github.com/dezign365/grc-copilot/blob/main/src/app/api/admin/packages/route.ts"
click node_email_service "https://github.com/dezign365/grc-copilot/blob/main/src/lib/email.ts"

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_dashboard,node_analyzer_ui,node_chat_ui,node_frameworks_ui,node_billing_ui,node_admin_ui,node_user toneBlue
class node_generate,node_stream_generate,node_analyze,node_questionnaire,node_brain,node_chat,node_framework_data,node_prompt,node_fallback toneAmber
class node_auth_callback,node_usage toneMint
class node_checkout,node_billing_portal,node_stripe_webhook,node_admin_packages toneRose
class node_supabase,node_google_ai,node_other_ai,node_stripe,node_email_service toneIndigo
```

## Components

### Workspace

- [Dashboard](https://github.com/dezign365/grc-copilot/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Compliance analyzer](https://github.com/dezign365/grc-copilot/blob/main/src/app/dashboard/ComplianceAnalyzer.tsx): `src/app/dashboard/ComplianceAnalyzer.tsx`
- [Chat workspace](https://github.com/dezign365/grc-copilot/blob/main/src/app/chat/page.tsx): `src/app/chat/page.tsx`
- [Framework catalog](https://github.com/dezign365/grc-copilot/blob/main/src/app/frameworks/page.tsx): `src/app/frameworks/page.tsx`
- [Billing dashboard](https://github.com/dezign365/grc-copilot/blob/main/src/components/BillingDashboard.tsx): `src/components/BillingDashboard.tsx`
- [Admin console](https://github.com/dezign365/grc-copilot/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`

### GRC Intelligence

- [Document generation](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/generate/route.ts): `src/app/api/generate/route.ts`
- [Stream generation](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/generate-stream/route.ts): `src/app/api/generate-stream/route.ts`
- [Document analysis](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/analyze/route.ts): `src/app/api/analyze/route.ts`
- [Spreadsheet questionnaire](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/analyze/questionnaire/route.ts): `src/app/api/analyze/questionnaire/route.ts`
- [Question planning](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/brain/route.ts): `src/app/api/brain/route.ts`
- [GRC chat](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Framework and control data](https://github.com/dezign365/grc-copilot/blob/main/src/lib/excellogFramework.ts): `src/lib/excellogFramework.ts`
- [GRC prompts](https://github.com/dezign365/grc-copilot/blob/main/src/lib/grc-system-prompt.ts): `src/lib/grc-system-prompt.ts`
- [LLM fallback](https://github.com/dezign365/grc-copilot/blob/main/src/lib/fallback-llm.ts): `src/lib/fallback-llm.ts`

### Identity and Usage

- [Auth callback](https://github.com/dezign365/grc-copilot/blob/main/src/app/auth/callback/route.ts): `src/app/auth/callback/route.ts`
- [Usage limits](https://github.com/dezign365/grc-copilot/blob/main/src/lib/usage.ts): `src/lib/usage.ts`

### Plans and Billing

- [Subscription checkout](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/checkout/route.ts): `src/app/api/checkout/route.ts`
- [Billing portal](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/billing/route.ts): `src/app/api/billing/route.ts`
- [Stripe webhook](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/webhook/stripe/route.ts): `src/app/api/webhook/stripe/route.ts`
- [Package management](https://github.com/dezign365/grc-copilot/blob/main/src/app/api/admin/packages/route.ts): `src/app/api/admin/packages/route.ts`

### External Services

- **Supabase auth and data**
- **Google Gemini**
- **Other AI providers**
- **Stripe**
- [Email service](https://github.com/dezign365/grc-copilot/blob/main/src/lib/email.ts): `src/lib/email.ts`

### Other components

- **GRC user**

## Connections

- GRC user → Dashboard: uses
- GRC user → Compliance analyzer: submits document
- GRC user → Chat workspace: asks questions
- GRC user → Framework catalog: browses
- GRC user → Billing dashboard: manages plan
- GRC user → Admin console: administers
- Document analysis → Supabase auth and data: authenticates and reads profile
- Document analysis → Usage limits: checks and records usage
- Document analysis → Google Gemini: validates and analyzes
- Spreadsheet questionnaire → Supabase auth and data: authenticates and reads policies
- Spreadsheet questionnaire → Google Gemini: answers requirements
- Spreadsheet questionnaire → Other AI providers: fallback answers
- Document generation → Supabase auth and data: authenticates and reads context
- Document generation → Usage limits: checks and records usage
- Document generation → GRC prompts: uses prompt
- Document generation → Google Gemini: generates structured document
- Document generation → Other AI providers: fallback generation
- Stream generation → Supabase auth and data: authenticates and reads profile
- Stream generation → Usage limits: checks and records usage
- Stream generation → GRC prompts: uses prompt
- Stream generation → Google Gemini: streams document
- GRC chat → Supabase auth and data: authenticates and reads profile
- GRC chat → Usage limits: checks and records usage
- GRC chat → Google Gemini: streams response
- GRC chat → Other AI providers: fallback response
- Question planning → Supabase auth and data: authenticates
- Question planning → LLM fallback: requests questions
- LLM fallback → Google Gemini: tries provider
- LLM fallback → Other AI providers: tries fallback
- Auth callback → Supabase auth and data: verifies session
- Auth callback → Email service: sends welcome email
- Subscription checkout → Supabase auth and data: authenticates and reads package
- Subscription checkout → Stripe: creates checkout session
- Billing portal → Supabase auth and data: reads customer profile
- Billing portal → Stripe: creates portal session
- Stripe webhook → Stripe: retrieves subscription and invoice
- Stripe webhook → Supabase auth and data: updates billing records
- Stripe webhook → Email service: sends payment email
- Package management → Supabase auth and data: checks admin and stores packages
- Package management → Stripe: syncs products and prices