divyanshu-hash/resolvex

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.