# eerreenn/sehirpulse-ai architecture

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

- Interactive diagram: https://gitdiagram.com/eerreenn/sehirpulse-ai
- Repository: https://github.com/eerreenn/sehirpulse-ai

## Overview

ŞehirPulse AI is a municipal request-management application. A citizen submits a report through the React form; the API validates it, the service invokes rule-based classification, department routing, and priority analysis, then stores the enriched ticket. Admins load, search, and filter saved tickets and update their status. The graph includes the documented admin and persistence capabilities; sampled source supports the principal call relationships shown. Some AI internals and frontend form behavior were not excerpted, so their internal links are limited to evidence in the adapter and README.

Main entry points: [`backend/app/routes/tickets.py`](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/routes/tickets.py) (Ticket endpoints), [`backend/app/ai_adapter.py`](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/ai_adapter.py) (AI adapter), [`frontend/src/App.jsx`](https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/App.jsx) (Route selection), [`backend/app/main.py`](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/main.py) (FastAPI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_app["Route selection<br/>[App.jsx]"]
  node_report["Report form<br/>[ReportForm.jsx]"]
  node_admin["Admin tickets<br/>[AdminTickets.jsx]"]
  node_client["API client<br/>[api.js]"]
end

subgraph group_api["API and workflow"]
  node_fastapi["FastAPI entry<br/>[main.py]"]
  node_routes["Ticket endpoints<br/>[tickets.py]"]
  node_schemas["Request schemas<br/>[ticket.py]"]
  node_service["Ticket workflow<br/>[ticket_service.py]"]
end

subgraph group_analysis["AI analysis"]
  node_adapter["AI adapter<br/>[ai_adapter.py]"]
  node_classifier["Category classifier<br/>[classify.py]"]
  node_routing["Department routing<br/>[routing.py]"]
  node_priority["Priority rules<br/>[priority_basic.py]"]
end

subgraph group_storage["Persistence"]
  node_ticket["Ticket model<br/>[ticket.py]"]
  node_database[("SQLAlchemy database<br/>[database.py]")]
end

node_citizen(("Citizen"))

node_citizen -->|"uses"| node_app
node_app -->|"renders"| node_report
node_app -->|"renders"| node_admin
node_report -->|"submits via"| node_client
node_admin -->|"loads and updates via"| node_client
node_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"registers"| node_routes
node_routes -->|"validates with"| node_schemas
node_routes -->|"calls"| node_service
node_service -->|"analyzes through"| node_adapter
node_adapter -->|"classifies with"| node_classifier
node_adapter -->|"routes with"| node_routing
node_adapter -->|"scores with"| node_priority
node_service -->|"creates and queries"| node_ticket
node_ticket -->|"uses base"| node_database
node_fastapi -->|"creates tables"| node_database
node_routes -->|"obtains sessions"| node_database

click node_app "https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/App.jsx"
click node_report "https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/components/ReportForm.jsx"
click node_admin "https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/components/AdminTickets.jsx"
click node_client "https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/main.py"
click node_routes "https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/routes/tickets.py"
click node_schemas "https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/schemas/ticket.py"
click node_service "https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/services/ticket_service.py"
click node_adapter "https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/ai_adapter.py"
click node_classifier "https://github.com/eerreenn/sehirpulse-ai/blob/main/ai/classify.py"
click node_routing "https://github.com/eerreenn/sehirpulse-ai/blob/main/ai/routing.py"
click node_priority "https://github.com/eerreenn/sehirpulse-ai/blob/main/ai/priority_basic.py"
click node_ticket "https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/models/ticket.py"
click node_database "https://github.com/eerreenn/sehirpulse-ai/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_admin,node_client toneBlue
class node_fastapi,node_routes,node_schemas,node_service toneAmber
class node_adapter,node_classifier,node_routing,node_priority toneMint
class node_ticket,node_database toneRose
class node_citizen toneIndigo
```

## Components

### Web application

- [Route selection](https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Report form](https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/components/ReportForm.jsx): `frontend/src/components/ReportForm.jsx`
- [Admin tickets](https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/components/AdminTickets.jsx): `frontend/src/components/AdminTickets.jsx`
- [API client](https://github.com/eerreenn/sehirpulse-ai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and workflow

- [FastAPI entry](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Ticket endpoints](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/routes/tickets.py): `backend/app/routes/tickets.py`
- [Request schemas](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/schemas/ticket.py): `backend/app/schemas/ticket.py`
- [Ticket workflow](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/services/ticket_service.py): `backend/app/services/ticket_service.py`

### AI analysis

- [AI adapter](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/ai_adapter.py): `backend/app/ai_adapter.py`
- [Category classifier](https://github.com/eerreenn/sehirpulse-ai/blob/main/ai/classify.py): `ai/classify.py`
- [Department routing](https://github.com/eerreenn/sehirpulse-ai/blob/main/ai/routing.py): `ai/routing.py`
- [Priority rules](https://github.com/eerreenn/sehirpulse-ai/blob/main/ai/priority_basic.py): `ai/priority_basic.py`

### Persistence

- [Ticket model](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/models/ticket.py): `backend/app/models/ticket.py`
- [SQLAlchemy database](https://github.com/eerreenn/sehirpulse-ai/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Citizen**

## Connections

- Citizen → Route selection: uses (evidence: `README.md`)
- Route selection → Report form: renders (evidence: `frontend/src/App.jsx`)
- Route selection → Admin tickets: renders (evidence: `frontend/src/App.jsx`)
- Report form → API client: submits via (evidence: `README.md`)
- Admin tickets → API client: loads and updates via (evidence: `frontend/src/components/AdminTickets.jsx`)
- API client → FastAPI entry: HTTP requests (evidence: `README.md`)
- FastAPI entry → Ticket endpoints: registers (evidence: `backend/app/main.py`)
- Ticket endpoints → Request schemas: validates with (evidence: `backend/app/routes/tickets.py`)
- Ticket endpoints → Ticket workflow: calls (evidence: `backend/app/routes/tickets.py`)
- Ticket workflow → AI adapter: analyzes through (evidence: `backend/app/services/ticket_service.py`)
- AI adapter → Category classifier: classifies with (evidence: `backend/app/ai_adapter.py`)
- AI adapter → Department routing: routes with (evidence: `backend/app/ai_adapter.py`)
- AI adapter → Priority rules: scores with (evidence: `backend/app/ai_adapter.py`)
- Ticket workflow → Ticket model: creates and queries (evidence: `backend/app/services/ticket_service.py`)
- Ticket model → SQLAlchemy database: uses base (evidence: `backend/app/models/ticket.py`)
- FastAPI entry → SQLAlchemy database: creates tables (evidence: `backend/app/main.py`)
- Ticket endpoints → SQLAlchemy database: obtains sessions (evidence: `backend/app/routes/tickets.py`)
