# colin-ff/gov-graph architecture

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

- Interactive diagram: https://gitdiagram.com/colin-ff/gov-graph
- Repository: https://github.com/colin-ff/gov-graph

## Overview

GovGraph is a university governance registry and analytics platform. Staff authenticate, create or resume a group’s Terms of Reference (ToR), optionally autofill it and check for possible duplicates, then submit it for review; approved governance data feeds the registry, relationship visualisation and superuser analytics. Separate capabilities include account registration and admin approval. The graph reflects documented routes and sampled service behavior; unsampled route-to-service wiring is represented only where the API or README establishes the capability.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/api/client.ts) (API client), [`frontend/src/App.tsx`](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/App.tsx) (GovGraph SPA), [`backend/app/db_schema`](https://github.com/colin-ff/gov-graph/tree/main/backend/app/db_schema) (Governance database), [`backend/app/services/tor_service.py`](https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/tor_service.py) (ToR validation and write)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["GovGraph SPA<br/>[App.tsx]"]
  node_auth_ui["Auth context<br/>[AuthContext.tsx]"]
  node_group_wizard["ToR wizard<br/>[NewGroupPage.tsx]"]
  node_registry_ui["Registry view<br/>[RegistryPage.tsx]"]
  node_graph_ui["Graph view"]
  node_analytics_ui["Analytics view<br/>[AnalyticsPage.tsx]"]
  node_admin_ui["Registration review"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["REST API"]
  node_auth_route["Auth endpoints<br/>[auth.py]"]
  node_register_route["User registration<br/>[register.py]"]
  node_admin_route["Admin registrations"]
  node_tor_route["ToR endpoints<br/>[tor.py]"]
  node_autofill_route["ToR autofill<br/>[tor_autofill.py]"]
  node_duplicates_route["Duplicate check<br/>[tor.py]"]
  node_submissions_route["Submission lifecycle<br/>[tor_submissions.py]"]
  node_groups_route["Group endpoints<br/>[groups.py]"]
  node_graph_route["Graph endpoint<br/>[graph.py]"]
  node_analytics_route["Analytics endpoint<br/>[analytics.py]"]
end

subgraph group_domain["Governance domain"]
  node_auth_service["Credential verification<br/>[auth_service.py]"]
  node_tor_service["ToR validation and write<br/>[tor_service.py]"]
  node_duplicate_service["Similarity matching"]
  node_submission_service["Submission workflow"]
  node_db[("Governance database")]
end

subgraph group_insights["Analysis and access"]
  node_analytics_engine["Governance analytics<br/>[main.py]"]
  node_auth_guard["Request identity<br/>[auth.py]"]
end

node_staff(("Staff user"))
node_admin(("Superuser"))

node_staff -->|"uses"| node_web
node_admin -->|"uses"| node_web
node_web -->|"provides auth"| node_auth_ui
node_web -->|"opens"| node_group_wizard
node_web -->|"opens"| node_registry_ui
node_web -->|"opens"| node_graph_ui
node_web -->|"opens"| node_analytics_ui
node_web -->|"opens"| node_admin_ui
node_auth_ui -->|"requests"| node_client
node_group_wizard -->|"submits ToR"| node_client
node_registry_ui -->|"loads registry"| node_client
node_graph_ui -->|"loads graph"| node_client
node_analytics_ui -->|"loads metrics"| node_client
node_admin_ui -->|"reviews requests"| node_client
node_client -->|"login"| node_auth_route
node_client -->|"register"| node_register_route
node_client -->|"approve or reject"| node_admin_route
node_client -->|"submit or read ToR"| node_tor_route
node_client -->|"uploads document"| node_autofill_route
node_client -->|"checks draft"| node_duplicates_route
node_client -->|"manages drafts"| node_submissions_route
node_client -->|"reads groups"| node_groups_route
node_client -->|"reads graph"| node_graph_route
node_client -->|"requests analytics"| node_analytics_route
node_auth_route -->|"verifies credentials"| node_auth_service
node_auth_service -->|"reads users"| node_db
node_auth_guard -->|"resolves caller"| node_db
node_tor_route -->|"validates and submits"| node_tor_service
node_tor_service -->|"writes governance data"| node_db
node_duplicates_route -->|"checks payload"| node_tor_service
node_tor_service -->|"finds candidates"| node_duplicate_service
node_duplicate_service -->|"reads embeddings"| node_db
node_submissions_route -->|"manages lifecycle"| node_submission_service
node_submission_service -->|"reads and writes submissions"| node_db
node_groups_route -->|"reads groups"| node_db
node_graph_route -->|"reads relationships"| node_db
node_analytics_route -->|"computes metrics"| node_analytics_engine
node_analytics_engine -->|"queries governance data"| node_db

click node_web "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/auth/AuthContext.tsx"
click node_group_wizard "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/NewGroupPage.tsx"
click node_registry_ui "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/RegistryPage.tsx"
click node_graph_ui "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/VisualisationPage.tsx"
click node_analytics_ui "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/AnalyticsPage.tsx"
click node_admin_ui "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/AdminRegistryPage.tsx"
click node_client "https://github.com/colin-ff/gov-graph/blob/main/frontend/src/api/client.ts"
click node_auth_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/auth.py"
click node_register_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/register.py"
click node_admin_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/admin_registrations.py"
click node_tor_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor.py"
click node_autofill_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor_autofill.py"
click node_duplicates_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor.py"
click node_submissions_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor_submissions.py"
click node_groups_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/groups.py"
click node_graph_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/graph.py"
click node_analytics_route "https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/analytics.py"
click node_auth_service "https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/auth_service.py"
click node_tor_service "https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/tor_service.py"
click node_duplicate_service "https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/embedding_service.py"
click node_submission_service "https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/tor_submission_service.py"
click node_db "https://github.com/colin-ff/gov-graph/tree/main/backend/app/db_schema"
click node_analytics_engine "https://github.com/colin-ff/gov-graph/blob/main/backend/app/analytics/main.py"
click node_auth_guard "https://github.com/colin-ff/gov-graph/blob/main/backend/app/auth.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_auth_ui,node_group_wizard,node_registry_ui,node_graph_ui,node_analytics_ui,node_admin_ui,node_client,node_staff,node_admin toneBlue
class node_auth_route,node_register_route,node_admin_route,node_tor_route,node_autofill_route,node_duplicates_route,node_submissions_route,node_groups_route,node_graph_route,node_analytics_route toneAmber
class node_auth_service,node_tor_service,node_duplicate_service,node_submission_service,node_db toneMint
class node_analytics_engine,node_auth_guard toneRose
```

## Components

### Web application

- [GovGraph SPA](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/auth/AuthContext.tsx): `frontend/src/auth/AuthContext.tsx`
- [ToR wizard](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/NewGroupPage.tsx): `frontend/src/pages/NewGroupPage.tsx`
- [Registry view](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/RegistryPage.tsx): `frontend/src/pages/RegistryPage.tsx`
- [Graph view](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/VisualisationPage.tsx): `frontend/src/pages/VisualisationPage.tsx`
- [Analytics view](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/AnalyticsPage.tsx): `frontend/src/pages/AnalyticsPage.tsx`
- [Registration review](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/pages/AdminRegistryPage.tsx): `frontend/src/pages/AdminRegistryPage.tsx`
- [API client](https://github.com/colin-ff/gov-graph/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### REST API

- [Auth endpoints](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [User registration](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/register.py): `backend/app/routes/register.py`
- [Admin registrations](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/admin_registrations.py): `backend/app/routes/admin_registrations.py`
- [ToR endpoints](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor.py): `backend/app/routes/tor.py`
- [ToR autofill](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor_autofill.py): `backend/app/routes/tor_autofill.py`
- [Duplicate check](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor.py): `backend/app/routes/tor.py`
- [Submission lifecycle](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/tor_submissions.py): `backend/app/routes/tor_submissions.py`
- [Group endpoints](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/groups.py): `backend/app/routes/groups.py`
- [Graph endpoint](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/graph.py): `backend/app/routes/graph.py`
- [Analytics endpoint](https://github.com/colin-ff/gov-graph/blob/main/backend/app/routes/analytics.py): `backend/app/routes/analytics.py`

### Governance domain

- [Credential verification](https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [ToR validation and write](https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/tor_service.py): `backend/app/services/tor_service.py`
- [Similarity matching](https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Submission workflow](https://github.com/colin-ff/gov-graph/blob/main/backend/app/services/tor_submission_service.py): `backend/app/services/tor_submission_service.py`
- [Governance database](https://github.com/colin-ff/gov-graph/tree/main/backend/app/db_schema): `backend/app/db_schema`

### Analysis and access

- [Governance analytics](https://github.com/colin-ff/gov-graph/blob/main/backend/app/analytics/main.py): `backend/app/analytics/main.py`
- [Request identity](https://github.com/colin-ff/gov-graph/blob/main/backend/app/auth.py): `backend/app/auth.py`

### Other components

- **Staff user**
- **Superuser**

## Connections

- Staff user → GovGraph SPA: uses
- Superuser → GovGraph SPA: uses
- GovGraph SPA → Auth context: provides auth
- GovGraph SPA → ToR wizard: opens
- GovGraph SPA → Registry view: opens
- GovGraph SPA → Graph view: opens
- GovGraph SPA → Analytics view: opens
- GovGraph SPA → Registration review: opens
- Auth context → API client: requests
- ToR wizard → API client: submits ToR
- Registry view → API client: loads registry
- Graph view → API client: loads graph
- Analytics view → API client: loads metrics
- Registration review → API client: reviews requests
- API client → Auth endpoints: login
- API client → User registration: register
- API client → Admin registrations: approve or reject
- API client → ToR endpoints: submit or read ToR
- API client → ToR autofill: uploads document
- API client → Duplicate check: checks draft
- API client → Submission lifecycle: manages drafts
- API client → Group endpoints: reads groups
- API client → Graph endpoint: reads graph
- API client → Analytics endpoint: requests analytics
- Auth endpoints → Credential verification: verifies credentials
- Credential verification → Governance database: reads users
- Request identity → Governance database: resolves caller
- ToR endpoints → ToR validation and write: validates and submits
- ToR validation and write → Governance database: writes governance data
- Duplicate check → ToR validation and write: checks payload
- ToR validation and write → Similarity matching: finds candidates
- Similarity matching → Governance database: reads embeddings
- Submission lifecycle → Submission workflow: manages lifecycle
- Submission workflow → Governance database: reads and writes submissions
- Group endpoints → Governance database: reads groups
- Graph endpoint → Governance database: reads relationships
- Analytics endpoint → Governance analytics: computes metrics
- Governance analytics → Governance database: queries governance data