# phat-smile/smart_parking_system architecture

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

- Interactive diagram: https://gitdiagram.com/phat-smile/smart_parking_system
- Repository: https://github.com/phat-smile/smart_parking_system

## Overview

This is a Smart Parking System technical foundation, not a completed user-facing parking product: the README explicitly says business user stories are not implemented. The intended request path is web client → YARP Gateway → business services, with service data and integration infrastructure behind them; the repository also contains concrete booking, identity, parking, payment, wallet and AI modules. The graph preserves those implemented domain stages and the documented messaging, IoT and observability capabilities. Edges rely on README statements or shown imports; unsampled service wiring is not inferred.

Main entry points: [`src/Gateway/Program.cs`](https://github.com/phat-smile/smart_parking_system/blob/develop/src/Gateway/Program.cs) (YARP Gateway), [`src/Services/Booking/Booking.Application`](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Booking/Booking.Application) (Reservations), [`src/Services/Identity/Identity.Application/Accounts`](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Identity/Identity.Application/Accounts) (Identity accounts), [`src/Services/Payment/Payment.Application`](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Payment/Payment.Application) (Payments and wallet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry"]
  node_web["Next.js web app"]
  node_gateway["YARP Gateway<br/>[Program.cs]"]
end

subgraph group_services["Business services"]
  node_booking["Reservations"]
  node_reservation_query["Reservation queries"]
  node_identity["Identity accounts<br/>[Accounts]"]
  node_vehicle_lookup["Vehicle lookup"]
  node_parking["Parking operations"]
  node_payment["Payments and wallet"]
  node_wallet_query["Wallet history"]
  node_wallet_domain["Wallet ledger rules<br/>[Wallet.cs]"]
end

subgraph group_ai["AI capabilities"]
  node_ai_app["AI service<br/>[main.py]"]
  node_arrival_api["Arrival availability API"]
  node_arrival_logic["Arrival estimation"]
  node_recommendations["Lot recommendations<br/>[recommendations.py]"]
end

subgraph group_platform["Platform infrastructure"]
  node_iot["IoT simulator<br/>[main.py]"]
  node_postgres[("PostgreSQL")]
  node_rabbitmq["RabbitMQ"]
  node_mqtt["MQTT"]
  node_observability["Telemetry stack"]
end

subgraph group_contracts["Integration contracts"]
  node_events["Integration events"]
  node_grpc_contracts["gRPC contracts"]
end

node_customer(("Web users"))

node_customer -->|"uses"| node_web
node_web -->|"routes API requests"| node_gateway
node_gateway -.->|"routes requests"| node_booking
node_gateway -.->|"routes requests"| node_identity
node_gateway -.->|"routes requests"| node_parking
node_gateway -.->|"routes requests"| node_payment
node_booking -->|"handles queries"| node_reservation_query
node_identity -->|"handles lookup"| node_vehicle_lookup
node_payment -->|"handles history"| node_wallet_query
node_wallet_query -->|"reads wallet"| node_wallet_domain
node_booking -.->|"persists data"| node_postgres
node_identity -.->|"persists data"| node_postgres
node_parking -.->|"persists data"| node_postgres
node_payment -.->|"persists data"| node_postgres
node_booking -.->|"publishes events"| node_rabbitmq
node_identity -.->|"publishes events"| node_rabbitmq
node_parking -.->|"publishes events"| node_rabbitmq
node_payment -.->|"publishes events"| node_rabbitmq
node_iot -->|"uses protocol"| node_mqtt
node_rabbitmq -.->|"carries event contracts"| node_events
node_booking -.->|"uses service contracts"| node_grpc_contracts
node_ai_app -->|"registers router"| node_arrival_api
node_arrival_api -.->|"uses application logic"| node_arrival_logic
node_ai_app -->|"registers router"| node_recommendations
node_gateway -.->|"routes requests"| node_ai_app
node_web -.->|"supports telemetry"| node_observability
node_gateway -->|"exports telemetry"| node_observability
node_booking -.->|"exports telemetry"| node_observability
node_identity -.->|"exports telemetry"| node_observability
node_parking -.->|"exports telemetry"| node_observability
node_payment -.->|"exports telemetry"| node_observability

click node_web "https://github.com/phat-smile/smart_parking_system/tree/develop/web"
click node_gateway "https://github.com/phat-smile/smart_parking_system/blob/develop/src/Gateway/Program.cs"
click node_booking "https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Booking/Booking.Application"
click node_reservation_query "https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Booking/Booking.Application/Reservations/Queries/GetMyReservations/GetMyReservationsQueryHandler.cs"
click node_identity "https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Identity/Identity.Application/Accounts"
click node_vehicle_lookup "https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Identity/Identity.Application/Vehicles/Lookup/LookupVehicleByPlateQueryHandler.cs"
click node_parking "https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Parking/Parking.Application"
click node_payment "https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Payment/Payment.Application"
click node_wallet_query "https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Payment/Payment.Application/Features/Wallets/Queries/GetWalletTransactions/GetWalletTransactionsQueryHandler.cs"
click node_wallet_domain "https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Payment/Payment.Domain/Entities/Wallet.cs"
click node_ai_app "https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/main.py"
click node_arrival_api "https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/api/arrival_availability.py"
click node_arrival_logic "https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/application/arrival_availability.py"
click node_recommendations "https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/api/recommendations.py"
click node_iot "https://github.com/phat-smile/smart_parking_system/blob/develop/edge/iot-simulator/src/main.py"
click node_events "https://github.com/phat-smile/smart_parking_system/tree/develop/contracts/events/ParkingSystem.Contracts.Events"
click node_grpc_contracts "https://github.com/phat-smile/smart_parking_system/tree/develop/contracts/grpc"

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_web,node_gateway,node_customer toneBlue
class node_booking,node_reservation_query,node_identity,node_vehicle_lookup,node_parking,node_payment,node_wallet_query,node_wallet_domain toneAmber
class node_ai_app,node_arrival_api,node_arrival_logic,node_recommendations toneMint
class node_iot,node_postgres,node_rabbitmq,node_mqtt,node_observability toneRose
class node_events,node_grpc_contracts toneIndigo
```

## Components

### Client entry

- [Next.js web app](https://github.com/phat-smile/smart_parking_system/tree/develop/web): `web`
- [YARP Gateway](https://github.com/phat-smile/smart_parking_system/blob/develop/src/Gateway/Program.cs): `src/Gateway/Program.cs`

### Business services

- [Reservations](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Booking/Booking.Application): `src/Services/Booking/Booking.Application`
- [Reservation queries](https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Booking/Booking.Application/Reservations/Queries/GetMyReservations/GetMyReservationsQueryHandler.cs): `src/Services/Booking/Booking.Application/Reservations/Queries/GetMyReservations/GetMyReservationsQueryHandler.cs`
- [Identity accounts](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Identity/Identity.Application/Accounts): `src/Services/Identity/Identity.Application/Accounts`
- [Vehicle lookup](https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Identity/Identity.Application/Vehicles/Lookup/LookupVehicleByPlateQueryHandler.cs): `src/Services/Identity/Identity.Application/Vehicles/Lookup/LookupVehicleByPlateQueryHandler.cs`
- [Parking operations](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Parking/Parking.Application): `src/Services/Parking/Parking.Application`
- [Payments and wallet](https://github.com/phat-smile/smart_parking_system/tree/develop/src/Services/Payment/Payment.Application): `src/Services/Payment/Payment.Application`
- [Wallet history](https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Payment/Payment.Application/Features/Wallets/Queries/GetWalletTransactions/GetWalletTransactionsQueryHandler.cs): `src/Services/Payment/Payment.Application/Features/Wallets/Queries/GetWalletTransactions/GetWalletTransactionsQueryHandler.cs`
- [Wallet ledger rules](https://github.com/phat-smile/smart_parking_system/blob/develop/src/Services/Payment/Payment.Domain/Entities/Wallet.cs): `src/Services/Payment/Payment.Domain/Entities/Wallet.cs`

### AI capabilities

- [AI service](https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/main.py): `ai/ai-service/app/main.py`
- [Arrival availability API](https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/api/arrival_availability.py): `ai/ai-service/app/api/arrival_availability.py`
- [Arrival estimation](https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/application/arrival_availability.py): `ai/ai-service/app/application/arrival_availability.py`
- [Lot recommendations](https://github.com/phat-smile/smart_parking_system/blob/develop/ai/ai-service/app/api/recommendations.py): `ai/ai-service/app/api/recommendations.py`

### Platform infrastructure

- [IoT simulator](https://github.com/phat-smile/smart_parking_system/blob/develop/edge/iot-simulator/src/main.py): `edge/iot-simulator/src/main.py`
- **PostgreSQL**
- **RabbitMQ**
- **MQTT**
- **Telemetry stack**

### Integration contracts

- [Integration events](https://github.com/phat-smile/smart_parking_system/tree/develop/contracts/events/ParkingSystem.Contracts.Events): `contracts/events/ParkingSystem.Contracts.Events`
- [gRPC contracts](https://github.com/phat-smile/smart_parking_system/tree/develop/contracts/grpc): `contracts/grpc`

### Other components

- **Web users**

## Connections

- Web users → Next.js web app: uses (evidence: `README.md`)
- Next.js web app → YARP Gateway: routes API requests (evidence: `README.md`)
- YARP Gateway → Reservations: routes requests
- YARP Gateway → Identity accounts: routes requests
- YARP Gateway → Parking operations: routes requests
- YARP Gateway → Payments and wallet: routes requests
- Reservations → Reservation queries: handles queries (evidence: `src/Services/Booking/Booking.Application/Reservations/Queries/GetMyReservations/GetMyReservationsQueryHandler.cs`)
- Identity accounts → Vehicle lookup: handles lookup (evidence: `src/Services/Identity/Identity.Application/Vehicles/Lookup/LookupVehicleByPlateQueryHandler.cs`)
- Payments and wallet → Wallet history: handles history (evidence: `src/Services/Payment/Payment.Application/Features/Wallets/Queries/GetWalletTransactions/GetWalletTransactionsQueryHandler.cs`)
- Wallet history → Wallet ledger rules: reads wallet (evidence: `src/Services/Payment/Payment.Application/Features/Wallets/Queries/GetWalletTransactions/GetWalletTransactionsQueryHandler.cs`)
- Reservations → PostgreSQL: persists data
- Identity accounts → PostgreSQL: persists data
- Parking operations → PostgreSQL: persists data
- Payments and wallet → PostgreSQL: persists data
- Reservations → RabbitMQ: publishes events
- Identity accounts → RabbitMQ: publishes events
- Parking operations → RabbitMQ: publishes events
- Payments and wallet → RabbitMQ: publishes events
- IoT simulator → MQTT: uses protocol (evidence: `README.md`)
- RabbitMQ → Integration events: carries event contracts
- Reservations → gRPC contracts: uses service contracts
- AI service → Arrival availability API: registers router (evidence: `ai/ai-service/app/main.py`)
- Arrival availability API → Arrival estimation: uses application logic (evidence: `ai/ai-service/app/api/arrival_availability.py`)
- AI service → Lot recommendations: registers router (evidence: `ai/ai-service/app/main.py`)
- YARP Gateway → AI service: routes requests
- Next.js web app → Telemetry stack: supports telemetry
- YARP Gateway → Telemetry stack: exports telemetry (evidence: `README.md`)
- Reservations → Telemetry stack: exports telemetry
- Identity accounts → Telemetry stack: exports telemetry
- Parking operations → Telemetry stack: exports telemetry
- Payments and wallet → Telemetry stack: exports telemetry
