# erkamvural/ev_csms architecture

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

- Interactive diagram: https://gitdiagram.com/erkamvural/ev_csms
- Repository: https://github.com/erkamvural/ev_csms

## Overview

1. **Overall shape**
   - This repository is a **modular monolith** for EV charging station management.
   - It has two deployable applications: a **FastAPI backend** and a **React/Vite frontend**, composed around business-capability modules rather than technical layers.

2. **Runtime and infrastructure**
   - Local/runtime stack is driven by **Docker Compose**.
   - Core infrastructure includes **PostgreSQL** with **PostGIS**, **Redis**, the backend API on port 8000, and the frontend on port 3000.
   - Database schema changes are managed with **Alembic** and run automatically at startup.

3. **Backend architecture pattern**
   - Each backend module follows the same internal structure: **domain**, **adapters**, **service_layer**, **entrypoints**, and **tests**.
   - This is strongly aligned with **Cosmic Python / DDD**: domain logic stays isolated, repositories and ORM mappings sit in adapters, and HTTP concerns live only in entrypoints.

4. **Main backend modules**
   - **identity**: authentication, user management, roles/permissions, JWT handling, RBAC.
   - **station_catalog**: charging station and charger metadata, nearby/searchable station views, and sync with external map data.
   - **charging**: charging session lifecycle, meter simulation, auto-stop scheduling, cost calculation.
   - **reservation**: reservation lifecycle, missed-reservation checks, reservation scheduling.
   - **payments**: wallet/top-up/hold/refund flows and integration with a payment gateway.
   - **notification**: email/SMS notification generation and delivery.
   - **audit**: immutable audit logging of actions.
   - **reporting**: analytical/read-model style data for dashboards and operational reporting.

5. **Core backend data flow**
   - Requests enter through a module’s **FastAPI router** in `entrypoints/api.py`.
   - The router calls a **service-layer handler**, which applies business rules inside the domain model.
   - Changes are persisted through a **Unit of Work** and **repository** abstraction into PostgreSQL.
   - Domain events are emitted through the shared messaging layer and can trigger other modules asynchronously or synchronously.

6. **Cross-module coordination**
   - The backend is intentionally decoupled: modules do not appear to share a single large service layer.
   - Coordination happens mainly through **domain events** and the **shared_kernel/message_bus.py** rather than direct tight coupling.
   - This is important for the architecture diagram: modules are peers connected through events, not a layered “global services” blob.

7. **Identity and access boundary**
   - Authentication uses **JWT**, and authorization is enforced with **RBAC**.
   - The frontend has an **AuthContext** and permission utilities, while the backend identity module owns token issuance, user repositories, and role logic.
   - Other modules likely consume identity claims rather than reimplementing access control.

8. **Station catalog and external geospatial services**
   - Station catalog is the boundary to **Google Maps / Google Places** integrations.
   - It also owns station syncing jobs and nearby-station queries, which depend on location-aware persistence in PostGIS.
   - On the frontend, this appears as map views, station lists, filters, and geolocation-driven discovery.

9. **Charging, reservation, and payments workflow**
   - Charging manages active sessions, meter progression, and stopping logic, including scheduled/automatic shutdown.
   - Reservation handles booking and expiry/missed-reservation handling.
   - Payments manages wallet balances, reserved funds, deductions, releases, refunds, and gateway integration; the presence of `iyzico_gateway.py` indicates an external PSP integration.
   - These three modules form the transactional core of the system and likely exchange events for deposit, reservation, and charging outcomes.

10. **Notifications, audit, and reporting as downstream consumers**
   - **notification** turns events into user-facing email/SMS messages using template rendering plus provider adapters.
   - **audit** records system actions for traceability and compliance.
   - **reporting** consumes persisted operational data to provide dashboard metrics, station performance, financial analytics, and user activity views.
   - These modules are read-heavy or event-driven and should be shown as downstream of the transactional modules.

11. **Frontend structure**
   - The frontend is organized by **feature slices** matching backend capabilities: identity, station catalog, charging, reservation, payments, notification, audit, reporting.
   - Each feature has its own **API client**, hooks, components, and types.
   - Shared UI primitives, a common Axios instance, and an event bus live under `src/shared`.

12. **Frontend-to-backend communication**
   - UI components call feature-specific API wrappers, which use a shared HTTP client to reach the backend.
   - Hooks encapsulate data fetching and mutations, while pages compose feature components into screens.
   - This makes the frontend a thin orchestration layer over backend module APIs rather than a separate domain system.

13. **Persistence and operational scripts**
   - PostgreSQL is the source of truth for application data.
   - Alembic migrations include the initial schema and seed data for admin/stations.
   - There are also repository-level scripts for backfills, checks, exports, and seed operations, which support operational data maintenance.

14. **Tests and quality boundaries**
   - Each backend module has both **unit** and **integration** tests, plus repository-level e2e tests.
   - This reinforces the module boundary: domain rules are tested apart from persistence and API wiring.
   - The repo also contains multiple test/report artifacts, suggesting significant verification around critical flows like charging, reservations, payments, and user deletion.

15. **How to draw the architecture**
   - A good diagram would show: **Frontend feature modules → backend FastAPI module routers → service layer → domain/repositories → PostgreSQL/PostGIS**.
   - Surrounding that core, show **external services** for Google Maps/Places, email/SMS, payment gateway, plus **Redis** and background schedulers.
   - Add **event flows** from charging/reservation/payments/identity into notification, audit, and reporting to capture the system’s main coupling mechanism.

Main entry points: [`EV_CSMS/frontend/src/app/App.tsx`](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/frontend/src/app/App.tsx) (App shell), [`EV_CSMS/backend/app/main.py`](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/backend/app/main.py) (API app), [`EV_CSMS/docker-compose.yaml`](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml) (PostgreSQL), [`EV_CSMS/backend/shared_kernel`](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/shared_kernel) (Shared kernel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React/Vite shell<br/>[App.tsx]"]
  node_frontend_shared["Shared UI<br/>Frontend shared"]
  node_frontend_identity["Identity UI<br/>Feature slice"]
  node_frontend_catalog["Station UI<br/>Feature slice"]
  node_frontend_charging["Charging UI<br/>Feature slice"]
  node_frontend_reservation["Reservation UI<br/>Feature slice"]
  node_frontend_payments["Payments UI<br/>Feature slice"]
  node_frontend_notification["Notification UI<br/>Feature slice"]
  node_frontend_audit["Audit UI<br/>Feature slice"]
  node_frontend_reporting["Reporting UI<br/>Feature slice"]
end

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>FastAPI bootstrap<br/>[main.py]"]
  node_backend_shared["Shared kernel<br/>Backend core"]
  node_identity_module["Identity<br/>Backend module"]
  node_catalog_module["Station catalog<br/>Backend module"]
  node_charging_module["Charging<br/>Backend module"]
  node_reservation_module["Reservation<br/>Backend module"]
  node_payments_module["Payments<br/>Backend module"]
  node_notification_module["Notification<br/>Backend module"]
  node_audit_module["Audit<br/>Backend module"]
  node_reporting_module["Reporting<br/>Backend module"]
end

subgraph group_infra["Infra"]
  node_db[("PostgreSQL<br/>Data store")]
  node_migrations["Alembic<br/>Migration layer"]
  node_runtime{{"Compose stack<br/>Deployment"}}
  node_redis[("Redis<br/>Cache/queue")]
end

subgraph group_external["External"]
  node_external_services(("External services<br/>3rd-party integrations"))
end

node_frontend_app -->|"uses"| node_frontend_shared
node_frontend_app -->|"composes"| node_frontend_identity
node_frontend_app -->|"composes"| node_frontend_catalog
node_frontend_app -->|"composes"| node_frontend_charging
node_frontend_app -->|"composes"| node_frontend_reservation
node_frontend_app -->|"composes"| node_frontend_payments
node_frontend_app -->|"composes"| node_frontend_notification
node_frontend_app -->|"composes"| node_frontend_audit
node_frontend_app -->|"composes"| node_frontend_reporting
node_frontend_identity -->|"API"| node_identity_module
node_frontend_catalog -->|"API"| node_catalog_module
node_frontend_charging -->|"API"| node_charging_module
node_frontend_reservation -->|"API"| node_reservation_module
node_frontend_payments -->|"API"| node_payments_module
node_frontend_notification -->|"API"| node_notification_module
node_frontend_audit -->|"API"| node_audit_module
node_frontend_reporting -->|"API"| node_reporting_module
node_backend_app -->|"routes"| node_identity_module
node_backend_app -->|"routes"| node_catalog_module
node_backend_app -->|"routes"| node_charging_module
node_backend_app -->|"routes"| node_reservation_module
node_backend_app -->|"routes"| node_payments_module
node_backend_app -->|"routes"| node_notification_module
node_backend_app -->|"routes"| node_audit_module
node_backend_app -->|"routes"| node_reporting_module
node_identity_module -->|"bus/auth"| node_backend_shared
node_catalog_module -->|"bus"| node_backend_shared
node_charging_module -->|"bus"| node_backend_shared
node_reservation_module -->|"bus"| node_backend_shared
node_payments_module -->|"bus"| node_backend_shared
node_notification_module -->|"bus"| node_backend_shared
node_audit_module -->|"bus"| node_backend_shared
node_reporting_module -->|"bus"| node_backend_shared
node_identity_module -->|"persist"| node_db
node_catalog_module -->|"persist"| node_db
node_charging_module -->|"persist"| node_db
node_reservation_module -->|"persist"| node_db
node_payments_module -->|"persist"| node_db
node_notification_module -->|"persist"| node_db
node_audit_module -->|"persist"| node_db
node_reporting_module -->|"read model"| node_db
node_migrations -->|"migrate"| node_db
node_runtime -->|"runs"| node_backend_app
node_runtime -->|"runs"| node_frontend_app
node_runtime -->|"includes"| node_db
node_runtime -->|"includes"| node_redis
node_catalog_module -->|"maps"| node_external_services
node_notification_module -->|"deliver"| node_external_services

click node_frontend_app "https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/frontend/src/app/App.tsx"
click node_frontend_shared "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/shared"
click node_frontend_identity "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/identity"
click node_frontend_catalog "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/station_catalog"
click node_frontend_charging "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/charging"
click node_frontend_reservation "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/reservation"
click node_frontend_payments "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/payments"
click node_frontend_notification "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/notification"
click node_frontend_audit "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/audit"
click node_frontend_reporting "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/reporting"
click node_backend_app "https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/backend/app/main.py"
click node_backend_shared "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/shared_kernel"
click node_identity_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/identity"
click node_catalog_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/station_catalog"
click node_charging_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/charging"
click node_reservation_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/reservation"
click node_payments_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/payments"
click node_notification_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/notification"
click node_audit_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/audit"
click node_reporting_module "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/reporting"
click node_db "https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml"
click node_migrations "https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/alembic"
click node_runtime "https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml"
click node_redis "https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml"

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_shared,node_frontend_identity,node_frontend_catalog,node_frontend_charging,node_frontend_reservation,node_frontend_payments,node_frontend_notification,node_frontend_audit,node_frontend_reporting toneBlue
class node_backend_app,node_backend_shared,node_identity_module,node_catalog_module,node_charging_module,node_reservation_module,node_payments_module,node_notification_module,node_audit_module,node_reporting_module toneAmber
class node_db,node_migrations,node_runtime,node_redis toneMint
class node_external_services toneRose
```

## Components

### Frontend

React/Vite feature-sliced UI

- [App shell](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/frontend/src/app/App.tsx): React/Vite shell · Routes, pages, and feature composition · `EV_CSMS/frontend/src/app/App.tsx`
- [Shared UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/shared): Frontend shared · Axios client, event bus, reusable primitives · `EV_CSMS/frontend/src/shared`
- [Identity UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/identity): Feature slice · Auth, profile, permissions, vehicles · `EV_CSMS/frontend/src/features/identity`
- [Station UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/station_catalog): Feature slice · Map views, discovery, station browsing · `EV_CSMS/frontend/src/features/station_catalog`
- [Charging UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/charging): Feature slice · Session control, progress, history · `EV_CSMS/frontend/src/features/charging`
- [Reservation UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/reservation): Feature slice · Create and manage reservations · `EV_CSMS/frontend/src/features/reservation`
- [Payments UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/payments): Feature slice · Wallet, top-up, transactions · `EV_CSMS/frontend/src/features/payments`
- [Notification UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/notification): Feature slice · Notification inbox and status · `EV_CSMS/frontend/src/features/notification`
- [Audit UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/audit): Feature slice · Audit log browsing and filters · `EV_CSMS/frontend/src/features/audit`
- [Reporting UI](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/frontend/src/features/reporting): Feature slice · Dashboards and analytics views · `EV_CSMS/frontend/src/features/reporting`

### Backend

FastAPI modular monolith

- [API app](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/backend/app/main.py): FastAPI bootstrap · Application startup and router assembly · `EV_CSMS/backend/app/main.py`
- [Shared kernel](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/shared_kernel): Backend core · Auth helpers, domain base, message bus · `EV_CSMS/backend/shared_kernel`
- [Identity](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/identity): Backend module · JWT auth, users, roles, RBAC · `EV_CSMS/backend/modules/identity`
- [Station catalog](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/station_catalog): Backend module · Stations, chargers, search, sync · `EV_CSMS/backend/modules/station_catalog`
- [Charging](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/charging): Backend module · Session lifecycle, meters, auto-stop · `EV_CSMS/backend/modules/charging`
- [Reservation](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/reservation): Backend module · Booking, expiry, missed checks · `EV_CSMS/backend/modules/reservation`
- [Payments](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/payments): Backend module · Wallet, holds, refunds, gateway · `EV_CSMS/backend/modules/payments`
- [Notification](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/notification): Backend module · Email/SMS generation and delivery · `EV_CSMS/backend/modules/notification`
- [Audit](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/audit): Backend module · Immutable action logging · `EV_CSMS/backend/modules/audit`
- [Reporting](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/modules/reporting): Backend module · Read models and analytics · `EV_CSMS/backend/modules/reporting`

### Infra

Local runtime, database, migrations

- [PostgreSQL](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml): Data store · Source of truth with PostGIS · `EV_CSMS/docker-compose.yaml`
- [Alembic](https://github.com/erkamvural/ev_csms/tree/main/EV_CSMS/backend/alembic): Migration layer · Schema and seed migrations · `EV_CSMS/backend/alembic`
- [Compose stack](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml): Deployment · Backend, frontend, Redis, database · `EV_CSMS/docker-compose.yaml`
- [Redis](https://github.com/erkamvural/ev_csms/blob/main/EV_CSMS/docker-compose.yaml): Cache/queue · Shared cache and async support · `EV_CSMS/docker-compose.yaml`

### External

Third-party services

- **External services**: 3rd-party integrations · Google Maps/Places, email/SMS, payment gateway

## Connections

- App shell → Shared UI: uses · Pages and features share HTTP, events, and UI primitives
- App shell → Identity UI: composes · App routes identity screens
- App shell → Station UI: composes · App routes station discovery screens
- App shell → Charging UI: composes · App routes charging screens
- App shell → Reservation UI: composes · App routes reservation screens
- App shell → Payments UI: composes · App routes wallet and payment screens
- App shell → Notification UI: composes · App routes notification screens
- App shell → Audit UI: composes · App routes audit screens
- App shell → Reporting UI: composes · App routes reporting screens
- Identity UI → Identity: API · Auth and profile flows call the identity backend
- Station UI → Station catalog: API · Station search and map views query catalog endpoints
- Charging UI → Charging: API · Session control talks to charging endpoints
- Reservation UI → Reservation: API · Reservation screens call reservation endpoints
- Payments UI → Payments: API · Wallet and transaction flows call payments endpoints
- Notification UI → Notification: API · Notification screens read notification endpoints
- Audit UI → Audit: API · Audit views read audit endpoints
- Reporting UI → Reporting: API · Dashboards read reporting endpoints
- API app → Identity: routes · FastAPI mounts identity routers
- API app → Station catalog: routes · FastAPI mounts station catalog routers
- API app → Charging: routes · FastAPI mounts charging routers
- API app → Reservation: routes · FastAPI mounts reservation routers
- API app → Payments: routes · FastAPI mounts payments routers
- API app → Notification: routes · FastAPI mounts notification routers
- API app → Audit: routes · FastAPI mounts audit routers
- API app → Reporting: routes · FastAPI mounts reporting routers
- Identity → Shared kernel: bus/auth · Uses shared auth and message bus primitives
- Station catalog → Shared kernel: bus · Publishes and consumes domain events through shared kernel
- Charging → Shared kernel: bus · Publishes and consumes domain events through shared kernel
- Reservation → Shared kernel: bus · Publishes and consumes domain events through shared kernel
- Payments → Shared kernel: bus · Publishes and consumes domain events through shared kernel
- Notification → Shared kernel: bus · Consumes domain events for delivery
- Audit → Shared kernel: bus · Consumes domain events for logging
- Reporting → Shared kernel: bus · Consumes persisted events and read data
- Identity → PostgreSQL: persist · Identity state stored in PostgreSQL
- Station catalog → PostgreSQL: persist · Stations and geospatial data stored in PostgreSQL/PostGIS
- Charging → PostgreSQL: persist · Charging sessions and meter state stored in PostgreSQL
- Reservation → PostgreSQL: persist · Reservations and expiry state stored in PostgreSQL
- Payments → PostgreSQL: persist · Wallet and transaction state stored in PostgreSQL
- Notification → PostgreSQL: persist · Notification records stored in PostgreSQL
- Audit → PostgreSQL: persist · Audit log stored immutably in PostgreSQL
- Reporting → PostgreSQL: read model · Reporting queries and analytics are read from PostgreSQL
- Alembic → PostgreSQL: migrate · Alembic creates and seeds schema
- Compose stack → API app: runs · Compose starts the API service
- Compose stack → App shell: runs · Compose starts the web client
- Compose stack → PostgreSQL: includes · Compose provides PostgreSQL/PostGIS
- Compose stack → Redis: includes · Compose provides Redis
- Station catalog → External services: maps · Station sync and nearby search use Google Maps/Places
- Notification → External services: deliver · Email and SMS providers are used for outbound notifications