# parasnavsar98/civicfix architecture

> Architecture diagram of the GitHub repository parasnavsar98/civicfix, 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/parasnavsar98/civicfix
- Repository: https://github.com/parasnavsar98/civicfix

## Overview

This repository combines CivicFix’s citizen-problem intake, AI classification and duplicate recommendations, human review, routing, version history, and audit trail with a separate university-matching and industry-collaboration backend. A React testing console exercises CivicFix’s end-to-end workflow and operational views. The matching engine ranks universities using seven explainable factors and supports assignment and marketplace flows. Links between the CivicFix API and its services are supported by the application wiring and service descriptions; some detailed service internals are unsampled, so uncertain calls are omitted.

Main entry points: [`backend/app/services/orchestrator.py`](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/orchestrator.py) (Intake orchestrator), [`backend/app/services/reviewer_service.py`](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/reviewer_service.py) (Reviewer service), [`UniversityMatchingAlgo/backend/app/main.py`](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/main.py) (Matching API), [`UniversityMatchingAlgo/backend/app/services/matching_engine.py`](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/matching_engine.py) (Scoring engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_civicfix["CivicFix workflow"]
  node_civic_api["CivicFix API<br/>[main.py]"]
  node_problem_api["Problem intake API<br/>[problems.py]"]
  node_intake["Intake orchestrator<br/>[orchestrator.py]"]
  node_classification_client["Classification client"]
  node_duplicate_client["Duplicate client"]
  node_problem_store[("Problem repository")]
  node_version_store[("Version repository")]
  node_duplicate_store[("Duplicate repository")]
  node_review_store[("Review repository")]
  node_audit_service["Audit service<br/>[audit_service.py]"]
  node_audit_store[("Audit repository")]
  node_review_api["Reviewer API<br/>[reviewer.py]"]
  node_review_service["Reviewer service"]
  node_routing_api["Routing API<br/>[routing.py]"]
  node_routing_service["Routing service<br/>[routing_service.py]"]
end

subgraph group_ai["AI services"]
  node_classification_api["Classification API<br/>[main.py]"]
  node_classifier["Classifier service<br/>[classifier.py]"]
  node_duplicate_api["Duplicate API<br/>[main.py]"]
  node_duplicate_engine["Duplicate detector"]
end

subgraph group_matching["University matching"]
  node_university_api["Matching API<br/>[main.py]"]
  node_matching_engine["Scoring engine<br/>[matching_engine.py]"]
  node_scoring_factors["Seven scoring factors"]
  node_assignment_flow["Assignment workflow"]
  node_marketplace["Solution marketplace<br/>[marketplace.py]"]
  node_collaboration["Collaboration service<br/>[collaboration.py]"]
  node_matching_db[("Matching database<br/>[database.py]")]
end

subgraph group_console["Testing interfaces"]
  node_console["Testing console<br/>[App.tsx]"]
  node_e2e_view["E2E walkthrough"]
  node_console_api["Backend API client<br/>[backend.ts]"]
  node_matching_demo["Matching demo UI<br/>[app.js]"]
end

node_citizen(("Problem submitter"))
node_reviewer(("Human reviewer"))
node_government(("Government / research"))

node_citizen -->|"submits problem"| node_problem_api
node_problem_api -->|"delegates intake"| node_intake
node_intake -->|"requests classification"| node_classification_client
node_classification_client -->|"posts classification"| node_classification_api
node_classification_api -->|"runs classifier"| node_classifier
node_intake -->|"requests candidates"| node_duplicate_client
node_duplicate_client -->|"checks duplicates"| node_duplicate_api
node_duplicate_api -->|"runs detection"| node_duplicate_engine
node_intake -->|"stores problem"| node_problem_store
node_intake -->|"stores version"| node_version_store
node_intake -->|"stores candidates"| node_duplicate_store
node_intake -->|"logs events"| node_audit_service
node_audit_service -->|"persists events"| node_audit_store
node_reviewer -->|"reviews cases"| node_review_api
node_review_api -->|"delegates actions"| node_review_service
node_review_service -->|"loads and saves"| node_problem_store
node_review_service -->|"writes versions"| node_version_store
node_review_service -->|"updates candidates"| node_duplicate_store
node_review_service -->|"records decisions"| node_review_store
node_review_service -->|"logs actions"| node_audit_service
node_reviewer -->|"requests routing"| node_routing_api
node_routing_api -->|"delegates routing"| node_routing_service
node_routing_service -->|"updates problem"| node_problem_store
node_routing_service -->|"logs routing"| node_audit_service
node_government -->|"receives routed cases"| node_routing_service
node_university_api -->|"runs ranking"| node_matching_engine
node_matching_engine -->|"scores factors"| node_scoring_factors
node_matching_engine -->|"reads universities and config"| node_matching_db
node_matching_engine -->|"stores ranked results"| node_matching_db
node_university_api -->|"manages assignments"| node_assignment_flow
node_university_api -->|"serves solutions"| node_marketplace
node_university_api -->|"manages collaborations"| node_collaboration
node_console -->|"renders walkthrough"| node_e2e_view
node_e2e_view -->|"requests workflow actions"| node_console_api
node_console_api -->|"calls backend"| node_civic_api
node_matching_demo -->|"calls matching API"| node_university_api

click node_civic_api "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/main.py"
click node_problem_api "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/api/problems.py"
click node_intake "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/orchestrator.py"
click node_classification_client "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/clients/classification_client.py"
click node_duplicate_client "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/clients/duplicate_client.py"
click node_problem_store "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/problem_repository.py"
click node_version_store "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/version_repository.py"
click node_duplicate_store "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/duplicate_repository.py"
click node_review_store "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/review_repository.py"
click node_audit_service "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/audit_service.py"
click node_audit_store "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/audit_repository.py"
click node_review_api "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/api/reviewer.py"
click node_review_service "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/reviewer_service.py"
click node_routing_api "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/api/routing.py"
click node_routing_service "https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/routing_service.py"
click node_classification_api "https://github.com/parasnavsar98/civicfix/blob/main/classification-engine/app/main.py"
click node_classifier "https://github.com/parasnavsar98/civicfix/blob/main/classification-engine/app/services/classifier.py"
click node_duplicate_api "https://github.com/parasnavsar98/civicfix/blob/main/duplicate-detection/app/main.py"
click node_duplicate_engine "https://github.com/parasnavsar98/civicfix/blob/main/duplicate-detection/app/services/duplicate_detector.py"
click node_university_api "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/main.py"
click node_matching_engine "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/matching_engine.py"
click node_scoring_factors "https://github.com/parasnavsar98/civicfix/tree/main/UniversityMatchingAlgo/backend/app/services/scoring"
click node_assignment_flow "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/assignment_workflow.py"
click node_marketplace "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/marketplace.py"
click node_collaboration "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/collaboration.py"
click node_matching_db "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/config/database.py"
click node_console "https://github.com/parasnavsar98/civicfix/blob/main/testing-console/src/App.tsx"
click node_e2e_view "https://github.com/parasnavsar98/civicfix/blob/main/testing-console/src/views/E2EPipelineView.tsx"
click node_console_api "https://github.com/parasnavsar98/civicfix/blob/main/testing-console/src/api/backend.ts"
click node_matching_demo "https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/frontend-test/app.js"

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_civic_api,node_problem_api,node_intake,node_classification_client,node_duplicate_client,node_problem_store,node_version_store,node_duplicate_store,node_review_store,node_audit_service,node_audit_store,node_review_api,node_review_service,node_routing_api,node_routing_service,node_reviewer toneBlue
class node_classification_api,node_classifier,node_duplicate_api,node_duplicate_engine toneAmber
class node_university_api,node_matching_engine,node_scoring_factors,node_assignment_flow,node_marketplace,node_collaboration,node_matching_db toneMint
class node_console,node_e2e_view,node_console_api,node_matching_demo toneRose
class node_citizen,node_government toneIndigo
```

## Components

### CivicFix workflow

- [CivicFix API](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/main.py): `backend/app/main.py`
- [Problem intake API](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/api/problems.py): `backend/app/api/problems.py`
- [Intake orchestrator](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/orchestrator.py): `backend/app/services/orchestrator.py`
- [Classification client](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/clients/classification_client.py): `backend/app/clients/classification_client.py`
- [Duplicate client](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/clients/duplicate_client.py): `backend/app/clients/duplicate_client.py`
- [Problem repository](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/problem_repository.py): `backend/app/repositories/problem_repository.py`
- [Version repository](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/version_repository.py): `backend/app/repositories/version_repository.py`
- [Duplicate repository](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/duplicate_repository.py): `backend/app/repositories/duplicate_repository.py`
- [Review repository](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/review_repository.py): `backend/app/repositories/review_repository.py`
- [Audit service](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`
- [Audit repository](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/repositories/audit_repository.py): `backend/app/repositories/audit_repository.py`
- [Reviewer API](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/api/reviewer.py): `backend/app/api/reviewer.py`
- [Reviewer service](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/reviewer_service.py): `backend/app/services/reviewer_service.py`
- [Routing API](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/api/routing.py): `backend/app/api/routing.py`
- [Routing service](https://github.com/parasnavsar98/civicfix/blob/main/backend/app/services/routing_service.py): `backend/app/services/routing_service.py`

### AI services

- [Classification API](https://github.com/parasnavsar98/civicfix/blob/main/classification-engine/app/main.py): `classification-engine/app/main.py`
- [Classifier service](https://github.com/parasnavsar98/civicfix/blob/main/classification-engine/app/services/classifier.py): `classification-engine/app/services/classifier.py`
- [Duplicate API](https://github.com/parasnavsar98/civicfix/blob/main/duplicate-detection/app/main.py): `duplicate-detection/app/main.py`
- [Duplicate detector](https://github.com/parasnavsar98/civicfix/blob/main/duplicate-detection/app/services/duplicate_detector.py): `duplicate-detection/app/services/duplicate_detector.py`

### University matching

- [Matching API](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/main.py): `UniversityMatchingAlgo/backend/app/main.py`
- [Scoring engine](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/matching_engine.py): `UniversityMatchingAlgo/backend/app/services/matching_engine.py`
- [Seven scoring factors](https://github.com/parasnavsar98/civicfix/tree/main/UniversityMatchingAlgo/backend/app/services/scoring): `UniversityMatchingAlgo/backend/app/services/scoring`
- [Assignment workflow](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/assignment_workflow.py): `UniversityMatchingAlgo/backend/app/services/assignment_workflow.py`
- [Solution marketplace](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/marketplace.py): `UniversityMatchingAlgo/backend/app/services/marketplace.py`
- [Collaboration service](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/services/collaboration.py): `UniversityMatchingAlgo/backend/app/services/collaboration.py`
- [Matching database](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/backend/app/config/database.py): `UniversityMatchingAlgo/backend/app/config/database.py`

### Testing interfaces

- [Testing console](https://github.com/parasnavsar98/civicfix/blob/main/testing-console/src/App.tsx): `testing-console/src/App.tsx`
- [E2E walkthrough](https://github.com/parasnavsar98/civicfix/blob/main/testing-console/src/views/E2EPipelineView.tsx): `testing-console/src/views/E2EPipelineView.tsx`
- [Backend API client](https://github.com/parasnavsar98/civicfix/blob/main/testing-console/src/api/backend.ts): `testing-console/src/api/backend.ts`
- [Matching demo UI](https://github.com/parasnavsar98/civicfix/blob/main/UniversityMatchingAlgo/frontend-test/app.js): `UniversityMatchingAlgo/frontend-test/app.js`

### Other components

- **Problem submitter**
- **Human reviewer**
- **Government / research**

## Connections

- Problem submitter → Problem intake API: submits problem
- Problem intake API → Intake orchestrator: delegates intake
- Intake orchestrator → Classification client: requests classification
- Classification client → Classification API: posts classification
- Classification API → Classifier service: runs classifier
- Intake orchestrator → Duplicate client: requests candidates
- Duplicate client → Duplicate API: checks duplicates
- Duplicate API → Duplicate detector: runs detection
- Intake orchestrator → Problem repository: stores problem
- Intake orchestrator → Version repository: stores version
- Intake orchestrator → Duplicate repository: stores candidates
- Intake orchestrator → Audit service: logs events
- Audit service → Audit repository: persists events
- Human reviewer → Reviewer API: reviews cases
- Reviewer API → Reviewer service: delegates actions
- Reviewer service → Problem repository: loads and saves
- Reviewer service → Version repository: writes versions
- Reviewer service → Duplicate repository: updates candidates
- Reviewer service → Review repository: records decisions
- Reviewer service → Audit service: logs actions
- Human reviewer → Routing API: requests routing
- Routing API → Routing service: delegates routing
- Routing service → Problem repository: updates problem
- Routing service → Audit service: logs routing
- Government / research → Routing service: receives routed cases
- Matching API → Scoring engine: runs ranking
- Scoring engine → Seven scoring factors: scores factors
- Scoring engine → Matching database: reads universities and config
- Scoring engine → Matching database: stores ranked results
- Matching API → Assignment workflow: manages assignments
- Matching API → Solution marketplace: serves solutions
- Matching API → Collaboration service: manages collaborations
- Testing console → E2E walkthrough: renders walkthrough
- E2E walkthrough → Backend API client: requests workflow actions
- Backend API client → CivicFix API: calls backend
- Matching demo UI → Matching API: calls matching API