erkamvural/ev_csms

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.