# akashwagh07/resolveit architecture

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

- Interactive diagram: https://gitdiagram.com/akashwagh07/resolveit
- Repository: https://github.com/akashwagh07/resolveit

## Overview

ResolveIt is a civic-complaint platform that takes citizen reports through AI-assisted understanding and deterministic scoring/routing, then supports assignment, repair evidence, approval, and citizen confirmation or dispute. The React app serves citizen, officer, and admin workflows; the FastAPI backend owns the decision and action paths. The README documents the closed-loop stages and review/audit capabilities. Some backend action, verification, and dashboard implementations were not excerpted, so those branches are shown only where the README or SOURCE INDEX supports them.

Main entry points: [`frontend/src/App.jsx`](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/App.jsx) (Role-based app), [`backend/app/pipeline.py`](https://github.com/akashwagh07/resolveit/blob/main/backend/app/pipeline.py) (Intake pipeline), [`frontend/src/lib/api.js`](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/lib/api.js) (API client), [`backend/app/agents/agent2.py`](https://github.com/akashwagh07/resolveit/blob/main/backend/app/agents/agent2.py) (Decision agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User workflows"]
  node_app["Role-based app<br/>[App.jsx]"]
  node_report["Report issue"]
  node_complaint_detail["Complaint detail"]
  node_officer_dashboard["Officer dashboard"]
  node_admin_dashboard["Admin dashboards<br/>[AdminDashboard.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_intake["Complaint intake"]
  node_complaint_api["Complaint endpoints<br/>[complaints.py]"]
  node_pipeline["Intake pipeline<br/>[pipeline.py]"]
  node_media_llm["Media and Gemini<br/>[llm.py]"]
end

subgraph group_decision["Analysis and routing"]
  node_agent1["Complaint classifier<br/>[agent1.py]"]
  node_agent2["Decision agent<br/>[agent2.py]"]
  node_severity["Severity and priority<br/>[severity.py]"]
  node_department["Department routing<br/>[department.py]"]
end

subgraph group_resolution["Resolution lifecycle"]
  node_commands["Validated commands<br/>[commands.py]"]
  node_executor["Command executor<br/>[executor.py]"]
  node_actions_api["Action endpoints<br/>[actions.py]"]
  node_verification["Resolution verification<br/>[verification.py]"]
end

subgraph group_platform["Identity and persistence"]
  node_auth_api["Identity endpoints<br/>[auth.py]"]
  node_auth["Demo identity<br/>[auth.py]"]
  node_models["Civic data models<br/>[models.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

node_citizen(("Citizen"))
node_officer(("Officer"))
node_admin(("Administrator"))

node_citizen -->|"uses"| node_app
node_officer -->|"uses"| node_app
node_admin -->|"uses"| node_app
node_app -->|"routes to"| node_report
node_app -->|"routes to"| node_complaint_detail
node_app -->|"routes to"| node_officer_dashboard
node_app -->|"routes to"| node_admin_dashboard
node_report -->|"submits through"| node_api_client
node_complaint_detail -->|"loads and acts through"| node_api_client
node_officer_dashboard -->|"uses"| node_api_client
node_admin_dashboard -->|"uses"| node_api_client
node_api_client -->|"requests complaints"| node_complaint_api
node_complaint_api -->|"submits report to"| node_pipeline
node_pipeline -->|"validates media with"| node_media_llm
node_pipeline -->|"classifies with"| node_agent1
node_pipeline -->|"requests decision from"| node_agent2
node_agent2 -->|"scores severity"| node_severity
node_agent2 -->|"routes category"| node_department
node_agent2 -->|"creates command"| node_commands
node_pipeline -->|"executes command"| node_executor
node_actions_api -->|"dispatches actions"| node_executor
node_actions_api -->|"uses verification"| node_verification
node_actions_api -->|"validates actions"| node_commands
node_complaint_api -->|"reads and writes"| node_models
node_executor -.->|"updates complaint state"| node_models
node_models -->|"persists in"| node_database
node_auth_api -->|"resolves caller"| node_auth
node_auth_api -->|"lists demo users"| node_models
node_app -->|"maintains client session"| node_auth

click node_app "https://github.com/akashwagh07/resolveit/blob/main/frontend/src/App.jsx"
click node_report "https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/ReportIssuePage.jsx"
click node_complaint_detail "https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/ComplaintDetailPage.jsx"
click node_officer_dashboard "https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/OfficerDashboard.jsx"
click node_admin_dashboard "https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_api_client "https://github.com/akashwagh07/resolveit/blob/main/frontend/src/lib/api.js"
click node_complaint_api "https://github.com/akashwagh07/resolveit/blob/main/backend/app/routers/complaints.py"
click node_pipeline "https://github.com/akashwagh07/resolveit/blob/main/backend/app/pipeline.py"
click node_media_llm "https://github.com/akashwagh07/resolveit/blob/main/backend/app/llm.py"
click node_agent1 "https://github.com/akashwagh07/resolveit/blob/main/backend/app/agents/agent1.py"
click node_agent2 "https://github.com/akashwagh07/resolveit/blob/main/backend/app/agents/agent2.py"
click node_severity "https://github.com/akashwagh07/resolveit/blob/main/backend/app/engines/severity.py"
click node_department "https://github.com/akashwagh07/resolveit/blob/main/backend/app/engines/department.py"
click node_commands "https://github.com/akashwagh07/resolveit/blob/main/backend/app/commands.py"
click node_executor "https://github.com/akashwagh07/resolveit/blob/main/backend/app/executor.py"
click node_actions_api "https://github.com/akashwagh07/resolveit/blob/main/backend/app/routers/actions.py"
click node_verification "https://github.com/akashwagh07/resolveit/blob/main/backend/app/verification.py"
click node_auth_api "https://github.com/akashwagh07/resolveit/blob/main/backend/app/routers/auth.py"
click node_auth "https://github.com/akashwagh07/resolveit/blob/main/backend/app/auth.py"
click node_models "https://github.com/akashwagh07/resolveit/blob/main/backend/app/models.py"
click node_database "https://github.com/akashwagh07/resolveit/blob/main/backend/app/database.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_report,node_complaint_detail,node_officer_dashboard,node_admin_dashboard,node_api_client toneBlue
class node_complaint_api,node_pipeline,node_media_llm toneAmber
class node_agent1,node_agent2,node_severity,node_department toneMint
class node_commands,node_executor,node_actions_api,node_verification toneRose
class node_auth_api,node_auth,node_models,node_database,node_citizen,node_officer,node_admin toneIndigo
```

## Components

### User workflows

- [Role-based app](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Report issue](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/ReportIssuePage.jsx): `frontend/src/pages/ReportIssuePage.jsx`
- [Complaint detail](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/ComplaintDetailPage.jsx): `frontend/src/pages/ComplaintDetailPage.jsx`
- [Officer dashboard](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/OfficerDashboard.jsx): `frontend/src/pages/OfficerDashboard.jsx`
- [Admin dashboards](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`
- [API client](https://github.com/akashwagh07/resolveit/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`

### Complaint intake

- [Complaint endpoints](https://github.com/akashwagh07/resolveit/blob/main/backend/app/routers/complaints.py): `backend/app/routers/complaints.py`
- [Intake pipeline](https://github.com/akashwagh07/resolveit/blob/main/backend/app/pipeline.py): `backend/app/pipeline.py`
- [Media and Gemini](https://github.com/akashwagh07/resolveit/blob/main/backend/app/llm.py): `backend/app/llm.py`

### Analysis and routing

- [Complaint classifier](https://github.com/akashwagh07/resolveit/blob/main/backend/app/agents/agent1.py): `backend/app/agents/agent1.py`
- [Decision agent](https://github.com/akashwagh07/resolveit/blob/main/backend/app/agents/agent2.py): `backend/app/agents/agent2.py`
- [Severity and priority](https://github.com/akashwagh07/resolveit/blob/main/backend/app/engines/severity.py): `backend/app/engines/severity.py`
- [Department routing](https://github.com/akashwagh07/resolveit/blob/main/backend/app/engines/department.py): `backend/app/engines/department.py`

### Resolution lifecycle

- [Validated commands](https://github.com/akashwagh07/resolveit/blob/main/backend/app/commands.py): `backend/app/commands.py`
- [Command executor](https://github.com/akashwagh07/resolveit/blob/main/backend/app/executor.py): `backend/app/executor.py`
- [Action endpoints](https://github.com/akashwagh07/resolveit/blob/main/backend/app/routers/actions.py): `backend/app/routers/actions.py`
- [Resolution verification](https://github.com/akashwagh07/resolveit/blob/main/backend/app/verification.py): `backend/app/verification.py`

### Identity and persistence

- [Identity endpoints](https://github.com/akashwagh07/resolveit/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Demo identity](https://github.com/akashwagh07/resolveit/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Civic data models](https://github.com/akashwagh07/resolveit/blob/main/backend/app/models.py): `backend/app/models.py`
- [SQL database](https://github.com/akashwagh07/resolveit/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Citizen**
- **Officer**
- **Administrator**

## Connections

- Citizen → Role-based app: uses
- Officer → Role-based app: uses
- Administrator → Role-based app: uses
- Role-based app → Report issue: routes to (evidence: `frontend/src/App.jsx`)
- Role-based app → Complaint detail: routes to (evidence: `frontend/src/App.jsx`)
- Role-based app → Officer dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Role-based app → Admin dashboards: routes to (evidence: `frontend/src/App.jsx`)
- Report issue → API client: submits through (evidence: `frontend/src/pages/ReportIssuePage.jsx`)
- Complaint detail → API client: loads and acts through (evidence: `frontend/src/pages/ComplaintDetailPage.jsx`)
- Officer dashboard → API client: uses
- Admin dashboards → API client: uses (evidence: `frontend/src/pages/AdminDashboard.jsx`)
- API client → Complaint endpoints: requests complaints (evidence: `frontend/src/lib/api.js`)
- Complaint endpoints → Intake pipeline: submits report to (evidence: `backend/app/routers/complaints.py`)
- Intake pipeline → Media and Gemini: validates media with (evidence: `backend/app/pipeline.py`)
- Intake pipeline → Complaint classifier: classifies with (evidence: `backend/app/pipeline.py`)
- Intake pipeline → Decision agent: requests decision from (evidence: `backend/app/pipeline.py`)
- Decision agent → Severity and priority: scores severity (evidence: `backend/app/agents/agent2.py`)
- Decision agent → Department routing: routes category (evidence: `backend/app/agents/agent2.py`)
- Decision agent → Validated commands: creates command (evidence: `backend/app/agents/agent2.py`)
- Intake pipeline → Command executor: executes command (evidence: `backend/app/pipeline.py`)
- Action endpoints → Command executor: dispatches actions (evidence: `backend/app/routers/actions.py`)
- Action endpoints → Resolution verification: uses verification (evidence: `backend/app/routers/actions.py`)
- Action endpoints → Validated commands: validates actions (evidence: `backend/app/routers/actions.py`)
- Complaint endpoints → Civic data models: reads and writes (evidence: `backend/app/routers/complaints.py`)
- Command executor → Civic data models: updates complaint state
- Civic data models → SQL database: persists in (evidence: `backend/app/models.py`)
- Identity endpoints → Demo identity: resolves caller (evidence: `backend/app/routers/auth.py`)
- Identity endpoints → Civic data models: lists demo users (evidence: `backend/app/routers/auth.py`)
- Role-based app → Demo identity: maintains client session (evidence: `frontend/src/App.jsx`)
