# thunderskull7/verifygrid architecture

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

- Interactive diagram: https://gitdiagram.com/thunderskull7/verifygrid
- Repository: https://github.com/thunderskull7/verifygrid

## Overview

VerifyGrid is a web platform for reconciling uploaded datasets, investigating discrepancies, recording review decisions, and producing cryptographically verifiable audit history. Auditors authenticate, select a project, upload and profile files, configure mappings and rules, run verification, then inspect, review, sign off, and export results; supervisors provide independent approval. The graph preserves major documented capabilities, but several route and service implementations were not sampled, so uncertain links are shown as unverified rather than asserted.

Main entry points: [`backend/app/services/verification_engine.py`](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/verification_engine.py) (Verification engine), [`backend/app/api/v1/router.py`](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/router.py) (API router), [`frontend/src/services/api.ts`](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/services/api.ts) (Typed API client), [`frontend/src/App.tsx`](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/App.tsx) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Auditor interface"]
  node_app["Workspace UI<br/>[App.tsx]"]
  node_authui["Authentication UI<br/>[AuthScreen.tsx]"]
  node_wizard["Reconciliation wizard"]
  node_resultsui["Results inspector"]
  node_reviewui["Review controls"]
  node_auditui["Audit history"]
  node_apiclient["Typed API client<br/>[api.ts]"]
  node_authctx["Auth context<br/>[AuthContext.tsx]"]
end

subgraph group_gateway["API and governance"]
  node_router["API router<br/>[router.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_verifyroute["Verification routes<br/>[verification.py]"]
  node_reviewroute["Review routes<br/>[review.py]"]
  node_auditroute["Audit routes<br/>[audit.py]"]
  node_uploadroute["Upload and profiling routes<br/>[uploads.py]"]
  node_security["Auth and project guards<br/>[deps.py]"]
end

subgraph group_processing["Reconciliation services"]
  node_ingestion["Streaming ingestion<br/>[ingestion.py]"]
  node_profiling["Dataset profiling"]
  node_preprocess["Preprocessing<br/>[preprocessing.py]"]
  node_verification["Verification engine"]
  node_rules["Rule evaluation<br/>[rule_engine.py]"]
  node_aggregation["Payment aggregation"]
  node_materiality["Financial materiality"]
  node_clustering["Exception clustering"]
  node_reviewservice["Review decisions<br/>[review_service.py]"]
  node_auditservice["Chained audit logging<br/>[audit_service.py]"]
  node_exports["Report export<br/>[export_service.py]"]
end

subgraph group_state["Persistent records"]
  node_dbsession["Database sessions<br/>[session.py]"]
  node_runs[("Verification records")]
  node_users[("User records<br/>[user.py]")]
end

node_auditor(("Auditor / Supervisor"))
node_database[("SQL database")]

node_auditor -->|"uses"| node_app
node_app -->|"renders"| node_authui
node_app -->|"renders"| node_wizard
node_app -->|"renders"| node_auditui
node_authui -->|"authenticates through"| node_apiclient
node_authctx -->|"manages token"| node_apiclient
node_wizard -->|"requests reconciliation"| node_apiclient
node_wizard -.->|"shows outcomes"| node_resultsui
node_resultsui -.->|"opens review"| node_reviewui
node_reviewui -->|"submits decisions"| node_apiclient
node_auditui -.->|"requests history"| node_apiclient
node_apiclient -->|"calls API"| node_router
node_router -->|"registers routes"| node_authroutes
node_router -->|"registers routes"| node_verifyroute
node_router -->|"registers routes"| node_reviewroute
node_router -->|"registers routes"| node_auditroute
node_router -->|"registers routes"| node_uploadroute
node_authroutes -->|"uses dependencies"| node_security
node_reviewroute -->|"uses dependencies"| node_security
node_reviewroute -->|"calls"| node_clustering
node_reviewroute -->|"calls"| node_reviewservice
node_auditroute -->|"calls"| node_auditservice
node_uploadroute -.->|"handles files"| node_ingestion
node_verifyroute -.->|"runs checks"| node_verification
node_verification -->|"uses"| node_preprocess
node_verification -->|"uses"| node_profiling
node_verification -->|"evaluates rules"| node_rules
node_verification -->|"reconciles allocations"| node_aggregation
node_verification -->|"calculates exposure"| node_materiality
node_verification -->|"groups exceptions"| node_clustering
node_reviewservice -->|"records decisions"| node_auditservice
node_verifyroute -.->|"exports reports"| node_exports
node_dbsession -->|"opens sessions"| node_database
node_authroutes -->|"reads users"| node_users
node_auditroute -->|"queries audit data"| node_database
node_reviewservice -->|"updates run state"| node_runs
node_verification -.->|"persists outcomes"| node_runs
node_auditservice -.->|"writes audit events"| node_database

click node_app "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/AuthScreen.tsx"
click node_wizard "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/ReconciliationWizard.tsx"
click node_resultsui "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/VerificationResultsView.tsx"
click node_reviewui "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/BulkReviewModal.tsx"
click node_auditui "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/AuditHistoryView.tsx"
click node_apiclient "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/services/api.ts"
click node_authctx "https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/context/AuthContext.tsx"
click node_router "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/router.py"
click node_authroutes "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_verifyroute "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/verification.py"
click node_reviewroute "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/review.py"
click node_auditroute "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/audit.py"
click node_uploadroute "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/uploads.py"
click node_security "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/deps.py"
click node_ingestion "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/ingestion.py"
click node_profiling "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/profiling_service.py"
click node_preprocess "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/preprocessing.py"
click node_verification "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/verification_engine.py"
click node_rules "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/rule_engine.py"
click node_aggregation "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/aggregation_engine.py"
click node_materiality "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/materiality_engine.py"
click node_clustering "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/clustering_service.py"
click node_reviewservice "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/review_service.py"
click node_auditservice "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/audit_service.py"
click node_exports "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/export_service.py"
click node_dbsession "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/db/session.py"
click node_runs "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/models/verification_run.py"
click node_users "https://github.com/thunderskull7/verifygrid/blob/main/backend/app/models/user.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_app,node_authui,node_wizard,node_resultsui,node_reviewui,node_auditui,node_apiclient,node_authctx toneBlue
class node_router,node_authroutes,node_verifyroute,node_reviewroute,node_auditroute,node_uploadroute,node_security,node_database toneAmber
class node_ingestion,node_profiling,node_preprocess,node_verification,node_rules,node_aggregation,node_materiality,node_clustering,node_reviewservice,node_auditservice,node_exports toneMint
class node_dbsession,node_runs,node_users toneRose
class node_auditor toneIndigo
```

## Components

### Auditor interface

- [Workspace UI](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Authentication UI](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/AuthScreen.tsx): `frontend/src/components/AuthScreen.tsx`
- [Reconciliation wizard](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/ReconciliationWizard.tsx): `frontend/src/components/ReconciliationWizard.tsx`
- [Results inspector](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/VerificationResultsView.tsx): `frontend/src/components/VerificationResultsView.tsx`
- [Review controls](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/BulkReviewModal.tsx): `frontend/src/components/BulkReviewModal.tsx`
- [Audit history](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/components/AuditHistoryView.tsx): `frontend/src/components/AuditHistoryView.tsx`
- [Typed API client](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Auth context](https://github.com/thunderskull7/verifygrid/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`

### API and governance

- [API router](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication routes](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Verification routes](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/verification.py): `backend/app/api/v1/endpoints/verification.py`
- [Review routes](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/review.py): `backend/app/api/v1/endpoints/review.py`
- [Audit routes](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/audit.py): `backend/app/api/v1/endpoints/audit.py`
- [Upload and profiling routes](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/v1/endpoints/uploads.py): `backend/app/api/v1/endpoints/uploads.py`
- [Auth and project guards](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`

### Reconciliation services

- [Streaming ingestion](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Dataset profiling](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/profiling_service.py): `backend/app/services/profiling_service.py`
- [Preprocessing](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/preprocessing.py): `backend/app/services/preprocessing.py`
- [Verification engine](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/verification_engine.py): `backend/app/services/verification_engine.py`
- [Rule evaluation](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/rule_engine.py): `backend/app/services/rule_engine.py`
- [Payment aggregation](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/aggregation_engine.py): `backend/app/services/aggregation_engine.py`
- [Financial materiality](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/materiality_engine.py): `backend/app/services/materiality_engine.py`
- [Exception clustering](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/clustering_service.py): `backend/app/services/clustering_service.py`
- [Review decisions](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/review_service.py): `backend/app/services/review_service.py`
- [Chained audit logging](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`
- [Report export](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/services/export_service.py): `backend/app/services/export_service.py`

### Persistent records

- [Database sessions](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Verification records](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/models/verification_run.py): `backend/app/models/verification_run.py`
- [User records](https://github.com/thunderskull7/verifygrid/blob/main/backend/app/models/user.py): `backend/app/models/user.py`

### Other components

- **Auditor / Supervisor**
- **SQL database**

## Connections

- Auditor / Supervisor → Workspace UI: uses
- Workspace UI → Authentication UI: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Reconciliation wizard: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Audit history: renders (evidence: `frontend/src/App.tsx`)
- Authentication UI → Typed API client: authenticates through (evidence: `frontend/src/components/AuthScreen.tsx`)
- Auth context → Typed API client: manages token (evidence: `frontend/src/context/AuthContext.tsx`)
- Reconciliation wizard → Typed API client: requests reconciliation (evidence: `frontend/src/components/ReconciliationWizard.tsx`)
- Reconciliation wizard → Results inspector: shows outcomes
- Results inspector → Review controls: opens review
- Review controls → Typed API client: submits decisions (evidence: `frontend/src/components/BulkReviewModal.tsx`)
- Audit history → Typed API client: requests history
- Typed API client → API router: calls API
- API router → Authentication routes: registers routes (evidence: `backend/app/api/v1/router.py`)
- API router → Verification routes: registers routes (evidence: `backend/app/api/v1/router.py`)
- API router → Review routes: registers routes (evidence: `backend/app/api/v1/router.py`)
- API router → Audit routes: registers routes (evidence: `backend/app/api/v1/router.py`)
- API router → Upload and profiling routes: registers routes (evidence: `backend/app/api/v1/router.py`)
- Authentication routes → Auth and project guards: uses dependencies (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Review routes → Auth and project guards: uses dependencies (evidence: `backend/app/api/v1/endpoints/review.py`)
- Review routes → Exception clustering: calls (evidence: `backend/app/api/v1/endpoints/review.py`)
- Review routes → Review decisions: calls (evidence: `backend/app/api/v1/endpoints/review.py`)
- Audit routes → Chained audit logging: calls (evidence: `backend/app/api/v1/endpoints/audit.py`)
- Upload and profiling routes → Streaming ingestion: handles files
- Verification routes → Verification engine: runs checks
- Verification engine → Preprocessing: uses (evidence: `backend/app/services/verification_engine.py`)
- Verification engine → Dataset profiling: uses (evidence: `backend/app/services/verification_engine.py`)
- Verification engine → Rule evaluation: evaluates rules (evidence: `backend/app/services/verification_engine.py`)
- Verification engine → Payment aggregation: reconciles allocations (evidence: `backend/app/services/verification_engine.py`)
- Verification engine → Financial materiality: calculates exposure (evidence: `backend/app/services/verification_engine.py`)
- Verification engine → Exception clustering: groups exceptions (evidence: `backend/app/services/verification_engine.py`)
- Review decisions → Chained audit logging: records decisions (evidence: `backend/app/services/review_service.py`)
- Verification routes → Report export: exports reports
- Database sessions → SQL database: opens sessions (evidence: `backend/app/db/session.py`)
- Authentication routes → User records: reads users (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Audit routes → SQL database: queries audit data (evidence: `backend/app/api/v1/endpoints/audit.py`)
- Review decisions → Verification records: updates run state (evidence: `backend/app/services/review_service.py`)
- Verification engine → Verification records: persists outcomes (evidence: `backend/app/services/verification_engine.py`)
- Chained audit logging → SQL database: writes audit events
