# viswaags/ai_report_compliance_system architecture

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

- Interactive diagram: https://gitdiagram.com/viswaags/ai_report_compliance_system
- Repository: https://github.com/viswaags/ai_report_compliance_system

## Overview

AI Report Compliance System supports role-based college event-report submission, template-driven validation, coordinator review, and archiving. The principal path is report upload through extraction, canonical mapping, compliance and semantic checks, then correction feedback or review and repository archiving. Separate capabilities include template analysis/versioning, club and event administration, dashboards, notifications, and Google Drive/email integrations. Edges rely on README statements or shown source references/calls; unsampled API and service internals are represented at their exact directories, with uncertain links omitted.

Main entry points: [`backend/app/services/report_pipeline_service.py`](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/report_pipeline_service.py) (Validation pipeline), [`backend/app/main.py`](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/workflows/review_workflow.py`](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/review_workflow.py) (Review workflow), [`frontend/src/lib/api.ts`](https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["React app<br/>[App.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_reportui["Report screens<br/>[ReportsPage.tsx]"]
  node_reviewui["Review screens<br/>[ReviewsPage.tsx]"]
  node_repohooks["Review queries<br/>[useReviews.ts]"]
end

subgraph group_access["Access and administration"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_admin["Clubs and events"]
  node_database[("Application database<br/>[db.py]")]
  node_dbmodels[("Domain records")]
end

subgraph group_reporting["Report validation"]
  node_reportsapi["Report endpoints<br/>[reports.py]"]
  node_reportflow["Report workflow<br/>[report_workflow.py]"]
  node_extract["Document extraction"]
  node_mapping["Canonical mapping"]
  node_pipeline["Validation pipeline"]
  node_compliance["Rule compliance"]
  node_semantic["Semantic validation"]
  node_feedback["Correction feedback"]
end

subgraph group_review["Review and archive"]
  node_reviewsapi["Review endpoints<br/>[reviews.py]"]
  node_reviewflow["Review workflow<br/>[review_workflow.py]"]
  node_reviewservice["Review decisions<br/>[review_service.py]"]
  node_records["Event records"]
  node_repository["Approved repository"]
end

subgraph group_integrations["Templates and integrations"]
  node_templates["Template workflows"]
  node_templatesvc["Template management"]
  node_notifications["Notifications"]
  node_drive["Google Drive"]
  node_email["Email delivery<br/>[email_service.py]"]
end

node_user(("System user"))

node_user -->|"uses"| node_web
node_web -.->|"loads API client"| node_webapi
node_reportui -.->|"requests data"| node_webapi
node_reviewui -.->|"uses queries"| node_repohooks
node_repohooks -->|"calls"| node_webapi
node_webapi -->|"HTTP requests"| node_api
node_api -->|"routes auth"| node_auth
node_api -->|"routes reports"| node_reportsapi
node_api -->|"routes reviews"| node_reviewsapi
node_api -->|"routes administration"| node_admin
node_reportsapi -.->|"runs workflow"| node_reportflow
node_reportflow -.->|"invokes pipeline"| node_pipeline
node_pipeline -->|"builds extraction"| node_extract
node_pipeline -->|"maps report"| node_mapping
node_pipeline -->|"validates rules"| node_compliance
node_pipeline -->|"checks semantics"| node_semantic
node_pipeline -->|"generates feedback"| node_feedback
node_pipeline -.->|"persists results"| node_database
node_templates -->|"stores template"| node_templatesvc
node_templates -->|"notifies coordinators"| node_notifications
node_reviewsapi -->|"runs decisions"| node_reviewflow
node_reviewflow -->|"executes review"| node_reviewservice
node_reviewflow -->|"records approval"| node_records
node_reviewflow -->|"notifies outcome"| node_notifications
node_reviewservice -->|"sends messages"| node_email
node_records -.->|"archives record"| node_repository
node_reportsapi -.->|"stores versions"| node_drive
node_templates -.->|"uploads templates"| node_drive
node_database -.->|"maps entities"| node_dbmodels

click node_web "https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/App.tsx"
click node_webapi "https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/lib/api.ts"
click node_reportui "https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/pages/ReportsPage.tsx"
click node_reviewui "https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/pages/ReviewsPage.tsx"
click node_repohooks "https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/hooks/useReviews.ts"
click node_api "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/main.py"
click node_auth "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/api/auth.py"
click node_admin "https://github.com/viswaags/ai_report_compliance_system/tree/main/backend/app/api"
click node_database "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/database/db.py"
click node_reportsapi "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/api/reports.py"
click node_reportflow "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/report_workflow.py"
click node_extract "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/raw_extraction_builder.py"
click node_mapping "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/template_guided_mapper.py"
click node_pipeline "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/report_pipeline_service.py"
click node_compliance "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/compliance_engine.py"
click node_semantic "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/semantic_validator.py"
click node_feedback "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/feedback_service.py"
click node_templates "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/template_workflow.py"
click node_templatesvc "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/template_service.py"
click node_reviewsapi "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/api/reviews.py"
click node_reviewflow "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/review_workflow.py"
click node_reviewservice "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/review_service.py"
click node_records "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/record_management_service.py"
click node_repository "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/repository_service.py"
click node_notifications "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/notification_service.py"
click node_drive "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/google_drive_service.py"
click node_email "https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/email_service.py"
click node_dbmodels "https://github.com/viswaags/ai_report_compliance_system/tree/main/backend/app/models"

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_webapi,node_reportui,node_reviewui,node_repohooks,node_user toneBlue
class node_api,node_auth,node_admin,node_database,node_dbmodels toneAmber
class node_reportsapi,node_reportflow,node_extract,node_mapping,node_pipeline,node_compliance,node_semantic,node_feedback toneMint
class node_reviewsapi,node_reviewflow,node_reviewservice,node_records,node_repository toneRose
class node_templates,node_templatesvc,node_notifications,node_drive,node_email toneIndigo
```

## Components

### Web application

- [React app](https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Report screens](https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/pages/ReportsPage.tsx): `frontend/src/pages/ReportsPage.tsx`
- [Review screens](https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/pages/ReviewsPage.tsx): `frontend/src/pages/ReviewsPage.tsx`
- [Review queries](https://github.com/viswaags/ai_report_compliance_system/blob/main/frontend/src/hooks/useReviews.ts): `frontend/src/hooks/useReviews.ts`

### Access and administration

- [FastAPI routes](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Clubs and events](https://github.com/viswaags/ai_report_compliance_system/tree/main/backend/app/api): `backend/app/api`
- [Application database](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/database/db.py): `backend/app/database/db.py`
- [Domain records](https://github.com/viswaags/ai_report_compliance_system/tree/main/backend/app/models): `backend/app/models`

### Report validation

- [Report endpoints](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`
- [Report workflow](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/report_workflow.py): `backend/app/workflows/report_workflow.py`
- [Document extraction](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/raw_extraction_builder.py): `backend/app/services/raw_extraction_builder.py`
- [Canonical mapping](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/template_guided_mapper.py): `backend/app/services/template_guided_mapper.py`
- [Validation pipeline](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/report_pipeline_service.py): `backend/app/services/report_pipeline_service.py`
- [Rule compliance](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/compliance_engine.py): `backend/app/services/compliance_engine.py`
- [Semantic validation](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/semantic_validator.py): `backend/app/services/semantic_validator.py`
- [Correction feedback](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/feedback_service.py): `backend/app/services/feedback_service.py`

### Review and archive

- [Review endpoints](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/api/reviews.py): `backend/app/api/reviews.py`
- [Review workflow](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/review_workflow.py): `backend/app/workflows/review_workflow.py`
- [Review decisions](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/review_service.py): `backend/app/services/review_service.py`
- [Event records](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/record_management_service.py): `backend/app/services/record_management_service.py`
- [Approved repository](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/repository_service.py): `backend/app/services/repository_service.py`

### Templates and integrations

- [Template workflows](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/workflows/template_workflow.py): `backend/app/workflows/template_workflow.py`
- [Template management](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/template_service.py): `backend/app/services/template_service.py`
- [Notifications](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`
- [Google Drive](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/google_drive_service.py): `backend/app/services/google_drive_service.py`
- [Email delivery](https://github.com/viswaags/ai_report_compliance_system/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`

### Other components

- **System user**

## Connections

- System user → React app: uses
- React app → API client: loads API client
- Report screens → API client: requests data
- Review screens → Review queries: uses queries
- Review queries → API client: calls (evidence: `frontend/src/hooks/useReviews.ts`)
- API client → FastAPI routes: HTTP requests
- FastAPI routes → Authentication: routes auth (evidence: `backend/app/main.py`)
- FastAPI routes → Report endpoints: routes reports (evidence: `backend/app/main.py`)
- FastAPI routes → Review endpoints: routes reviews (evidence: `backend/app/main.py`)
- FastAPI routes → Clubs and events: routes administration (evidence: `backend/app/main.py`)
- Report endpoints → Report workflow: runs workflow
- Report workflow → Validation pipeline: invokes pipeline
- Validation pipeline → Document extraction: builds extraction (evidence: `backend/app/services/report_pipeline_service.py`)
- Validation pipeline → Canonical mapping: maps report (evidence: `backend/app/services/report_pipeline_service.py`)
- Validation pipeline → Rule compliance: validates rules (evidence: `backend/app/services/report_pipeline_service.py`)
- Validation pipeline → Semantic validation: checks semantics (evidence: `backend/app/services/report_pipeline_service.py`)
- Validation pipeline → Correction feedback: generates feedback (evidence: `backend/app/services/report_pipeline_service.py`)
- Validation pipeline → Application database: persists results
- Template workflows → Template management: stores template
- Template workflows → Notifications: notifies coordinators
- Review endpoints → Review workflow: runs decisions (evidence: `backend/app/api/reviews.py`)
- Review workflow → Review decisions: executes review (evidence: `backend/app/workflows/review_workflow.py`)
- Review workflow → Event records: records approval (evidence: `backend/app/workflows/review_workflow.py`)
- Review workflow → Notifications: notifies outcome (evidence: `backend/app/workflows/review_workflow.py`)
- Review decisions → Email delivery: sends messages (evidence: `backend/app/services/review_service.py`)
- Event records → Approved repository: archives record
- Report endpoints → Google Drive: stores versions
- Template workflows → Google Drive: uploads templates
- Application database → Domain records: maps entities (evidence: `backend/app/models/review.py`)
