# divyanshu-hash/resolvex architecture

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

- Interactive diagram: https://gitdiagram.com/divyanshu-hash/resolvex
- Repository: https://github.com/divyanshu-hash/resolvex

## Overview

1. **Overall shape**
   ResolveX is a split frontend/backend system: a React single-page app for users and admins, a FastAPI service for business logic and API access, and a MySQL database as the system of record. There is also a filesystem upload area for complaint evidence.

2. **Client layer**
   The frontend is a Vite + React 18 app using React Router, Axios, and Tailwind CSS. Its main architectural role is presentation and session-aware navigation: `AuthContext` holds login state, `App.tsx` wires routes and role guards, and `Layout`/`Sidebar` provide the shared shell. Pages map directly to product workflows such as dashboard, complaint creation, complaint detail, analytics, users, login, and registration.

3. **API layer**
   The backend is a FastAPI application composed of route modules under `backend/routers`. Each router owns a functional slice of the domain: auth, complaints, evidence, feedback, analytics, and users. This keeps the API boundary clear and makes it easy to diagram as a set of resource-oriented endpoints behind a single app entrypoint in `main.py`.

4. **Identity and access control**
   Authentication is JWT-based with role checks enforced server-side through `dependencies.py`. The system is explicitly role-driven: normal user, staff, admin, and super admin. The frontend mirrors this with protected routes and conditional menu visibility, but the backend is the source of truth for authorization.

5. **Complaint workflow core**
   The complaint subsystem is the central domain flow. Complaints move through a lifecycle from submission to categorization, assignment, progress, resolution, and closure. The complaint router and related services handle state changes, assignment, and audit logging, while the UI exposes both list and detail views for tracking.

6. **Automation services**
   Several backend services add automation around the core workflow. `categorization.py` infers category and priority from complaint text, `escalation.py` handles overdue complaint escalation via a scheduled job, and `complaint_log.py` writes timeline/audit entries. `main.py` is responsible for wiring the scheduler into the app lifecycle.

7. **Evidence handling**
   Evidence is a separate subsystem because it mixes metadata and file storage. The API lets users upload and retrieve images/PDFs tied to a complaint; metadata is stored in MySQL while the actual files land in the configured upload directory on disk. This creates a clear boundary between transactional data and binary assets.

8. **Feedback and closure**
   Feedback is only meaningful after resolution, so it sits downstream of the complaint lifecycle. The feedback endpoints let users rate completed complaints, creating a post-resolution signal that can be used for accountability and reporting. This is a lightweight but distinct subdomain.

9. **Analytics and reporting**
   The analytics module is read-heavy and aggregates operational metrics such as total/open/resolved/escalated complaints, trends by category/priority/month, and staff performance. The frontend Analytics page renders these metrics with charts, so the diagram should show analytics as a backend query/aggregation path feeding a dedicated dashboard view.

10. **Persistence model**
   MySQL is the primary persistent store, with schema defined in `database/schema.sql` and ORM models in `backend/models.py`. SQLAlchemy provides the data-access layer, while Pydantic schemas define API contracts. This gives a clean separation between transport models, ORM entities, and database schema.

11. **Operational bootstrap and data seeding**
   `backend/config.py` reads environment-driven settings such as database URL, JWT secret, upload path, SLA timing, and escalation toggle. There is also a seed/migration path in the backend and a SQL schema file for initial setup, indicating the repo supports both direct schema initialization and app-level bootstrapping.

12. **Key external boundaries**
   The important architectural boundaries are: browser to SPA, SPA to FastAPI over HTTP, FastAPI to MySQL via SQLAlchemy, and FastAPI to the local upload directory for evidence files. Background escalation is the main non-request-driven flow, so it should be drawn as a scheduler-triggered backend process that mutates complaint state independently of user traffic.

Main entry points: [`frontend/src/App.tsx`](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/App.tsx) (App shell), [`backend/routers/complaints.py`](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/complaints.py) (Complaints API), [`backend/routers/__init__.py`](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/__init__.py) (Routers), [`database/schema.sql`](https://github.com/divyanshu-hash/resolvex/blob/main/database/schema.sql) (MySQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React entry<br/>[App.tsx]"]
  node_frontend_auth(("Auth state<br/>React context<br/>[AuthContext.tsx]"))
  node_frontend_layout["Layout<br/>shell component<br/>[Layout.tsx]"]
  node_frontend_sidebar["Sidebar<br/>nav component<br/>[Sidebar.tsx]"]
  node_frontend_dashboard["Dashboard<br/>page<br/>[Dashboard.tsx]"]
  node_frontend_complaints_list["Complaints<br/>page<br/>[ComplaintsList.tsx]"]
  node_frontend_complaint_create["New complaint<br/>page"]
  node_frontend_complaint_detail["Complaint detail<br/>page"]
  node_frontend_analytics["Analytics<br/>page<br/>[Analytics.tsx]"]
  node_frontend_users["Users<br/>page<br/>[Users.tsx]"]
  node_frontend_login["Login<br/>page<br/>[Login.tsx]"]
  node_frontend_register["Register<br/>page<br/>[Register.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API app<br/>FastAPI entry<br/>[main.py]"]
  node_backend_dependencies(("Access control<br/>auth deps<br/>[dependencies.py]"))
  node_backend_routers["Routers<br/>API modules<br/>[__init__.py]"]
  node_backend_complaints["Complaints API<br/>router<br/>[complaints.py]"]
  node_backend_evidence["Evidence API<br/>router<br/>[evidence.py]"]
  node_backend_feedback["Feedback API<br/>router<br/>[feedback.py]"]
  node_backend_analytics["Analytics API<br/>router<br/>[analytics.py]"]
  node_backend_users["Users API<br/>router<br/>[users.py]"]
  node_backend_auth["Auth API<br/>router<br/>[auth.py]"]
  node_backend_categorization{{"Categorization<br/>[categorization.py]"}}
  node_backend_escalation{{"Escalation<br/>[escalation.py]"}}
  node_backend_log{{"Complaint log<br/>[complaint_log.py]"}}
  node_backend_config["Config<br/>settings<br/>[config.py]"]
end

subgraph group_data["Data"]
  node_db_mysql[("MySQL<br/>database<br/>[schema.sql]")]
  node_fs_uploads["Uploads<br/>filesystem"]
end

node_frontend_app -->|"uses session"| node_frontend_auth
node_frontend_app -->|"renders shell"| node_frontend_layout
node_frontend_layout -->|"includes nav"| node_frontend_sidebar
node_frontend_app -->|"routes to"| node_frontend_login
node_frontend_app -->|"routes to"| node_frontend_register
node_frontend_app -->|"routes to"| node_frontend_dashboard
node_frontend_app -->|"routes to"| node_frontend_complaints_list
node_frontend_app -->|"routes to"| node_frontend_complaint_create
node_frontend_app -->|"routes to"| node_frontend_complaint_detail
node_frontend_app -->|"routes to"| node_frontend_analytics
node_frontend_app -->|"routes to"| node_frontend_users
node_backend_main -->|"mounts"| node_backend_routers
node_backend_main -->|"enforces"| node_backend_dependencies
node_backend_main -->|"reads settings"| node_backend_config
node_backend_routers -->|"includes"| node_backend_auth
node_backend_routers -->|"includes"| node_backend_complaints
node_backend_routers -->|"includes"| node_backend_evidence
node_backend_routers -->|"includes"| node_backend_feedback
node_backend_routers -->|"includes"| node_backend_analytics
node_backend_routers -->|"includes"| node_backend_users
node_backend_complaints -->|"uses"| node_backend_categorization
node_backend_complaints -->|"writes"| node_backend_log
node_backend_complaints -.->|"updates via"| node_backend_escalation
node_backend_feedback -->|"depends on"| node_backend_complaints
node_backend_evidence -->|"stores files"| node_fs_uploads
node_backend_evidence -->|"stores metadata"| node_db_mysql
node_backend_auth -->|"reads/writes"| node_db_mysql
node_backend_users -->|"reads/writes"| node_db_mysql
node_backend_complaints -->|"reads/writes"| node_db_mysql
node_backend_feedback -->|"reads/writes"| node_db_mysql
node_backend_analytics -->|"queries"| node_db_mysql
node_backend_escalation -.->|"mutates"| node_db_mysql
node_frontend_analytics -->|"fetches metrics"| node_backend_analytics
node_frontend_complaints_list -->|"fetches complaints"| node_backend_complaints
node_frontend_complaint_create -->|"submits"| node_backend_complaints
node_frontend_complaint_detail -->|"fetches detail"| node_backend_complaints
node_frontend_complaint_detail -->|"uploads evidence"| node_backend_evidence
node_frontend_login -->|"authenticates"| node_backend_auth
node_frontend_register -->|"registers"| node_backend_auth
node_frontend_users -->|"administers"| node_backend_users

click node_frontend_app "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/App.tsx"
click node_frontend_auth "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/context/AuthContext.tsx"
click node_frontend_layout "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/components/Layout.tsx"
click node_frontend_sidebar "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/components/Sidebar.tsx"
click node_frontend_dashboard "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Dashboard.tsx"
click node_frontend_complaints_list "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/ComplaintsList.tsx"
click node_frontend_complaint_create "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/ComplaintCreate.tsx"
click node_frontend_complaint_detail "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/ComplaintDetail.tsx"
click node_frontend_analytics "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Analytics.tsx"
click node_frontend_users "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Users.tsx"
click node_frontend_login "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Login.tsx"
click node_frontend_register "https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Register.tsx"
click node_backend_main "https://github.com/divyanshu-hash/resolvex/blob/main/backend/main.py"
click node_backend_dependencies "https://github.com/divyanshu-hash/resolvex/blob/main/backend/dependencies.py"
click node_backend_routers "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/__init__.py"
click node_backend_complaints "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/complaints.py"
click node_backend_evidence "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/evidence.py"
click node_backend_feedback "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/feedback.py"
click node_backend_analytics "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/analytics.py"
click node_backend_users "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/users.py"
click node_backend_auth "https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/auth.py"
click node_backend_categorization "https://github.com/divyanshu-hash/resolvex/blob/main/backend/services/categorization.py"
click node_backend_escalation "https://github.com/divyanshu-hash/resolvex/blob/main/backend/services/escalation.py"
click node_backend_log "https://github.com/divyanshu-hash/resolvex/blob/main/backend/services/complaint_log.py"
click node_backend_config "https://github.com/divyanshu-hash/resolvex/blob/main/backend/config.py"
click node_db_mysql "https://github.com/divyanshu-hash/resolvex/blob/main/database/schema.sql"
click node_fs_uploads "https://github.com/divyanshu-hash/resolvex/tree/main/backend/uploads"

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_frontend_app,node_frontend_auth,node_frontend_layout,node_frontend_sidebar,node_frontend_dashboard,node_frontend_complaints_list,node_frontend_complaint_create,node_frontend_complaint_detail,node_frontend_analytics,node_frontend_users,node_frontend_login,node_frontend_register toneBlue
class node_backend_main,node_backend_dependencies,node_backend_routers,node_backend_complaints,node_backend_evidence,node_backend_feedback,node_backend_analytics,node_backend_users,node_backend_auth,node_backend_categorization,node_backend_escalation,node_backend_log,node_backend_config toneAmber
class node_db_mysql,node_fs_uploads toneMint
```

## Components

### Frontend

React SPA for users and admins.

- [App shell](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/App.tsx): React entry · Bootstraps routing, guards, and top-level UI composition. · `frontend/src/App.tsx`
- [Auth state](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/context/AuthContext.tsx): React context · Holds login/session state for the SPA. · `frontend/src/context/AuthContext.tsx`
- [Layout](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/components/Layout.tsx): shell component · Shared page structure for authenticated views. · `frontend/src/components/Layout.tsx`
- [Sidebar](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/components/Sidebar.tsx): nav component · Role-aware navigation menu and section links. · `frontend/src/components/Sidebar.tsx`
- [Dashboard](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Dashboard.tsx): page · Primary landing view for operational status. · `frontend/src/pages/Dashboard.tsx`
- [Complaints](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/ComplaintsList.tsx): page · Lists complaints and routes into detail views. · `frontend/src/pages/ComplaintsList.tsx`
- [New complaint](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/ComplaintCreate.tsx): page · Creates complaint submissions from users. · `frontend/src/pages/ComplaintCreate.tsx`
- [Complaint detail](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/ComplaintDetail.tsx): page · Shows complaint state, history, and related evidence. · `frontend/src/pages/ComplaintDetail.tsx`
- [Analytics](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Analytics.tsx): page · Renders charts and metrics for reporting. · `frontend/src/pages/Analytics.tsx`
- [Users](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Users.tsx): page · Admin view for user management. · `frontend/src/pages/Users.tsx`
- [Login](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Login.tsx): page · Authentication entry point for existing users. · `frontend/src/pages/Login.tsx`
- [Register](https://github.com/divyanshu-hash/resolvex/blob/main/frontend/src/pages/Register.tsx): page · Account creation flow for new users. · `frontend/src/pages/Register.tsx`

### Backend

FastAPI service with domain routers and automation.

- [API app](https://github.com/divyanshu-hash/resolvex/blob/main/backend/main.py): FastAPI entry · Wires routers, lifecycle hooks, and scheduler startup. · `backend/main.py`
- [Access control](https://github.com/divyanshu-hash/resolvex/blob/main/backend/dependencies.py): auth deps · Server-side JWT and role enforcement helpers. · `backend/dependencies.py`
- [Routers](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/__init__.py): API modules · Resource-oriented HTTP endpoints grouped by domain. · `backend/routers/__init__.py`
- [Complaints API](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/complaints.py): router · Complaint submission, lifecycle updates, assignment, and audit flow. · `backend/routers/complaints.py`
- [Evidence API](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/evidence.py): router · Uploads and retrieves complaint attachments. · `backend/routers/evidence.py`
- [Feedback API](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/feedback.py): router · Captures post-resolution user feedback. · `backend/routers/feedback.py`
- [Analytics API](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/analytics.py): router · Aggregates operational metrics for dashboards. · `backend/routers/analytics.py`
- [Users API](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/users.py): router · User and staff administration endpoints. · `backend/routers/users.py`
- [Auth API](https://github.com/divyanshu-hash/resolvex/blob/main/backend/routers/auth.py): router · Login, registration, and token issuance endpoints. · `backend/routers/auth.py`
- [Categorization](https://github.com/divyanshu-hash/resolvex/blob/main/backend/services/categorization.py): service · Infers complaint category and priority from text. · `backend/services/categorization.py`
- [Escalation](https://github.com/divyanshu-hash/resolvex/blob/main/backend/services/escalation.py): service · Scheduler-driven overdue complaint escalation logic. · `backend/services/escalation.py`
- [Complaint log](https://github.com/divyanshu-hash/resolvex/blob/main/backend/services/complaint_log.py): service · Writes timeline and audit trail entries. · `backend/services/complaint_log.py`
- [Config](https://github.com/divyanshu-hash/resolvex/blob/main/backend/config.py): settings · Environment-driven application settings. · `backend/config.py`

### Data

Persistent store and file upload boundary.

- [MySQL](https://github.com/divyanshu-hash/resolvex/blob/main/database/schema.sql): database · System of record for users, complaints, evidence metadata, and feedback. · `database/schema.sql`
- [Uploads](https://github.com/divyanshu-hash/resolvex/tree/main/backend/uploads): filesystem · Local storage for complaint evidence files. · `backend/uploads`

## Connections

- App shell → Auth state: uses session · App shell reads authentication state for guards and navigation.
- App shell → Layout: renders shell · Top-level app composes the shared authenticated layout.
- Layout → Sidebar: includes nav · Layout embeds the main navigation sidebar.
- App shell → Login: routes to · Public route for sign-in.
- App shell → Register: routes to · Public route for account creation.
- App shell → Dashboard: routes to · Authenticated landing page.
- App shell → Complaints: routes to · Complaint listing workflow.
- App shell → New complaint: routes to · Complaint submission workflow.
- App shell → Complaint detail: routes to · Complaint inspection workflow.
- App shell → Analytics: routes to · Reporting dashboard route.
- App shell → Users: routes to · Admin-only user management route.
- API app → Routers: mounts · Main application registers domain routers.
- API app → Access control: enforces · API routes rely on shared auth and role checks.
- API app → Config: reads settings · Bootstrapping uses environment-driven configuration.
- Routers → Auth API: includes · Authentication endpoints.
- Routers → Complaints API: includes · Complaint lifecycle endpoints.
- Routers → Evidence API: includes · Attachment upload and retrieval endpoints.
- Routers → Feedback API: includes · Post-resolution feedback endpoints.
- Routers → Analytics API: includes · Operational metrics endpoints.
- Routers → Users API: includes · User administration endpoints.
- Complaints API → Categorization: uses · Complaint intake can infer category and priority.
- Complaints API → Complaint log: writes · State changes and assignments create audit entries.
- Complaints API → Escalation: updates via · Overdue complaints are escalated by background processing.
- Feedback API → Complaints API: depends on · Feedback is tied to resolved complaints.
- Evidence API → Uploads: stores files · Binary evidence is saved to local disk.
- Evidence API → MySQL: stores metadata · Attachment metadata persists in the database.
- Auth API → MySQL: reads/writes · Credentials and user records live in MySQL.
- Users API → MySQL: reads/writes · User administration persists to MySQL.
- Complaints API → MySQL: reads/writes · Complaint records, status, and assignments persist to MySQL.
- Feedback API → MySQL: reads/writes · Feedback records persist to MySQL.
- Analytics API → MySQL: queries · Aggregations are computed from stored operational data.
- Escalation → MySQL: mutates · Escalation job updates complaint state in storage.
- Analytics → Analytics API: fetches metrics · Analytics view consumes aggregated backend metrics.
- Complaints → Complaints API: fetches complaints · List view reads complaint collections.
- New complaint → Complaints API: submits · Create form posts new complaints.
- Complaint detail → Complaints API: fetches detail · Detail view loads complaint state and history.
- Complaint detail → Evidence API: uploads evidence · Detail view can attach complaint evidence.
- Login → Auth API: authenticates · Login exchanges credentials for a session token.
- Register → Auth API: registers · Registration creates a new account through the auth API.
- Users → Users API: administers · Users page manages staff and user accounts.