# deveshjha-00/its architecture

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

- Interactive diagram: https://gitdiagram.com/deveshjha-00/its
- Repository: https://github.com/deveshjha-00/its

## Overview

1. **What this repo is**
   - ParkSmart is a two-tier smart parking demo: a **React/Tailwind frontend** for drivers and admins, and a **Flask REST API** backed by **SQLite**.
   - The core domain is parking-slot state, bookings, QR-based arrival/departure, auto-release of expired reservations, and admin analytics.

2. **Top-level runtime split**
   - The **frontend** runs as a browser UI on port 3000 and talks to the backend over HTTP.
   - The **backend** runs as a Python Flask service on port 5000 and owns all business rules and persistence.
   - There is no separate message broker or microservice boundary; scheduler and API live in the same backend process.

3. **Backend architecture**
   - `backend/app/__init__.py` is the app factory and likely wires Flask, CORS, config, and the scheduler.
   - The backend is organized into:
     - `routes/` for HTTP endpoints,
     - `services/` for business logic,
     - `models/` for data shape/domain objects,
     - `db/` for schema creation, seeding, and helper scripts,
     - `jobs/` for background tasks.

4. **Domain/data model**
   - The persistent schema centers on three tables/models:
     - **slots**: slot identity, category, status, hourly rate.
     - **bookings**: booking lifecycle, vehicle/driver details, arrival/check-in/check-out, charge.
     - **occupancy_history**: hourly snapshots for analytics and prediction.
   - The repo includes SQLite database files (`parksmart.db`) and scripts to initialize and seed demo data.

5. **Core booking and slot-state flow**
   - The main data flow is: **frontend action → public API route → booking/slot service → SQLite**.
   - Slot state transitions are strictly managed in the service layer: `available`, `reserved`, `occupied`, `unavailable`.
   - Booking lifecycle is similarly managed: `confirmed → checked_in → completed`, with `expired` and `cancelled` as terminal paths.
   - This service layer is the main architectural boundary that prevents the UI from mutating state directly.

6. **Public API boundary**
   - `backend/app/routes/public.py` exposes driver-facing endpoints such as:
     - list slots,
     - create/cancel bookings,
     - check-in/check-out using QR payloads,
     - walk-in booking,
     - peak-hour prediction.
   - These endpoints are the only entry point for the driver UI and are intended to be stateless HTTP calls.

7. **Admin API boundary**
   - `backend/app/routes/admin.py` exposes privileged endpoints for:
     - login,
     - dashboard analytics,
     - slot updates/force release,
     - session logs,
     - utilization heatmap.
   - Admin access is intentionally simple: the README describes password-based authorization using a bearer token-style header, rather than a full multi-user auth system.

8. **Background processing**
   - `backend/app/jobs/auto_release.py` implements the scheduled cleanup loop that expires unclaimed reservations.
   - The scheduler runs inside the backend process and reclaims slots periodically, which means reservation expiry is an internal backend concern rather than a client-side timer.
   - This job is important to the architecture because it mutates slot and booking state asynchronously from user requests.

9. **Frontend architecture**
   - `frontend/src/App.js` is the top-level router/entry point for the browser app.
   - The UI is split into page-level containers:
     - `pages/DriverPage.js` for the slot map, booking modal, QR check-in/out, and receipt flow,
     - `pages/AdminPage.js` for analytics, slot management, and session logs,
     - `pages/Landing.js` for the entry screen.
   - `src/api/client.js` is the central HTTP client, so all UI state changes funnel through a single backend API boundary.

10. **UI component structure and data flow**
    - Reusable components in `components/` represent the visual building blocks: slot cards/grids, booking modal, dashboard cards, charts, toast/feedback, navbar, filters, and loading states.
    - The driver page appears to poll for slot availability, so the frontend is not push-based; it refreshes from the backend on an interval.
    - Analytics views depend on backend aggregation data, and charts are rendered client-side from API responses.

11. **Operational/deployment shape**
    - `dockerfile` indicates containerized deployment support.
    - `Jenkinsfile` and `Jenkinsfile-nopush` show CI/CD automation is part of the repo’s delivery model.
    - `sonar-project.properties` suggests static analysis/quality scanning is expected in the pipeline.
    - These files affect how the system is built and validated, but not the runtime domain architecture.

12. **Important architectural constraints**
    - The system is intentionally simple and demo-friendly: **SQLite**, **polling instead of WebSockets**, and **single-process scheduling**.
    - That makes the architecture easy to diagram: one browser client, one Flask backend, one local database, with an internal scheduler and clear route/service/db layering.
    - The main external dependency is the browser-facing frontend; there are no visible third-party runtime services such as payment gateways or auth providers.

Main entry points: [`backend/app/routes/public.py`](https://github.com/deveshjha-00/its/blob/main/backend/app/routes/public.py) (Public API), [`backend/app/services/slot_service.py`](https://github.com/deveshjha-00/its/blob/main/backend/app/services/slot_service.py) (Slot svc), [`frontend/src/App.js`](https://github.com/deveshjha-00/its/blob/main/frontend/src/App.js) (App shell), [`backend/app/__init__.py`](https://github.com/deveshjha-00/its/blob/main/backend/app/__init__.py) (App factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["App shell<br/>React entry<br/>[App.js]"]
  node_fe_client["API client<br/>HTTP client<br/>[client.js]"]
  node_fe_driver["Driver page<br/>UI page<br/>[DriverPage.js]"]
  node_fe_admin["Admin page<br/>UI page<br/>[AdminPage.js]"]
  node_fe_landing["Landing<br/>UI page<br/>[Landing.js]"]
  node_fe_components["UI kit<br/>shared components<br/>[SlotGrid.js]"]
end

subgraph group_backend["Backend"]
  node_be_factory["App factory<br/>Flask bootstrap<br/>[__init__.py]"]
  node_be_public["Public API<br/>routes<br/>[public.py]"]
  node_be_admin["Admin API<br/>routes<br/>[admin.py]"]
  node_be_booking["Booking svc<br/>[booking_service.py]"]
  node_be_slot["Slot svc<br/>[slot_service.py]"]
  node_be_analytics["Analytics svc"]
  node_be_predict["Prediction svc"]
  node_be_models["Domain models<br/>[booking.py]"]
  node_be_db["DB layer<br/>sqlite helpers<br/>[init.py]"]
  node_be_job["Auto release<br/>background job<br/>[auto_release.py]"]
end

subgraph group_delivery["Delivery"]
  node_deliver_ci["CI pipeline<br/>delivery"]
  node_deliver_container["Container<br/>deploy spec"]
end

node_fe_app -->|"routes"| node_fe_driver
node_fe_app -->|"routes"| node_fe_admin
node_fe_app -->|"routes"| node_fe_landing
node_fe_driver -->|"calls"| node_fe_client
node_fe_admin -->|"calls"| node_fe_client
node_fe_driver -->|"uses"| node_fe_components
node_fe_admin -->|"uses"| node_fe_components
node_fe_client -->|"HTTP"| node_be_public
node_fe_client -->|"HTTP"| node_be_admin
node_be_factory -->|"registers"| node_be_public
node_be_factory -->|"registers"| node_be_admin
node_be_factory -->|"starts"| node_be_job
node_be_public -->|"uses"| node_be_booking
node_be_public -->|"uses"| node_be_slot
node_be_public -->|"uses"| node_be_predict
node_be_admin -->|"uses"| node_be_analytics
node_be_admin -->|"uses"| node_be_slot
node_be_booking -->|"reads/writes"| node_be_models
node_be_slot -->|"reads/writes"| node_be_models
node_be_analytics -->|"aggregates"| node_be_models
node_be_predict -->|"analyzes"| node_be_models
node_be_booking -->|"persists"| node_be_db
node_be_slot -->|"persists"| node_be_db
node_be_analytics -->|"reads"| node_be_db
node_be_job -.->|"expires"| node_be_booking
node_be_job -.->|"reclaims"| node_be_slot
node_deliver_ci -->|"builds"| node_deliver_container
node_deliver_ci -->|"tests"| node_be_factory
node_deliver_ci -->|"tests"| node_fe_app

click node_fe_app "https://github.com/deveshjha-00/its/blob/main/frontend/src/App.js"
click node_fe_client "https://github.com/deveshjha-00/its/blob/main/frontend/src/api/client.js"
click node_fe_driver "https://github.com/deveshjha-00/its/blob/main/frontend/src/pages/DriverPage.js"
click node_fe_admin "https://github.com/deveshjha-00/its/blob/main/frontend/src/pages/AdminPage.js"
click node_fe_landing "https://github.com/deveshjha-00/its/blob/main/frontend/src/pages/Landing.js"
click node_fe_components "https://github.com/deveshjha-00/its/blob/main/frontend/src/components/SlotGrid.js"
click node_be_factory "https://github.com/deveshjha-00/its/blob/main/backend/app/__init__.py"
click node_be_public "https://github.com/deveshjha-00/its/blob/main/backend/app/routes/public.py"
click node_be_admin "https://github.com/deveshjha-00/its/blob/main/backend/app/routes/admin.py"
click node_be_booking "https://github.com/deveshjha-00/its/blob/main/backend/app/services/booking_service.py"
click node_be_slot "https://github.com/deveshjha-00/its/blob/main/backend/app/services/slot_service.py"
click node_be_analytics "https://github.com/deveshjha-00/its/blob/main/backend/app/services/analytics_service.py"
click node_be_predict "https://github.com/deveshjha-00/its/blob/main/backend/app/services/prediction_service.py"
click node_be_models "https://github.com/deveshjha-00/its/blob/main/backend/app/models/booking.py"
click node_be_db "https://github.com/deveshjha-00/its/blob/main/backend/app/db/init.py"
click node_be_job "https://github.com/deveshjha-00/its/blob/main/backend/app/jobs/auto_release.py"
click node_deliver_ci "https://github.com/deveshjha-00/its/tree/main/Jenkinsfile"
click node_deliver_container "https://github.com/deveshjha-00/its/tree/main/dockerfile"

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_fe_app,node_fe_client,node_fe_driver,node_fe_admin,node_fe_landing,node_fe_components toneBlue
class node_be_factory,node_be_public,node_be_admin,node_be_booking,node_be_slot,node_be_analytics,node_be_predict,node_be_models,node_be_db,node_be_job toneAmber
class node_deliver_ci,node_deliver_container toneMint
```

## Components

### Frontend

Browser UI for drivers and admins

- [App shell](https://github.com/deveshjha-00/its/blob/main/frontend/src/App.js): React entry · Top-level browser app and route composition · `frontend/src/App.js`
- [API client](https://github.com/deveshjha-00/its/blob/main/frontend/src/api/client.js): HTTP client · Central frontend boundary for backend requests · `frontend/src/api/client.js`
- [Driver page](https://github.com/deveshjha-00/its/blob/main/frontend/src/pages/DriverPage.js): UI page · Driver-facing booking, QR, and slot flow · `frontend/src/pages/DriverPage.js`
- [Admin page](https://github.com/deveshjha-00/its/blob/main/frontend/src/pages/AdminPage.js): UI page · Admin analytics, slot control, and logs · `frontend/src/pages/AdminPage.js`
- [Landing](https://github.com/deveshjha-00/its/blob/main/frontend/src/pages/Landing.js): UI page · Entry screen for the demo · `frontend/src/pages/Landing.js`
- [UI kit](https://github.com/deveshjha-00/its/blob/main/frontend/src/components/SlotGrid.js): shared components · Reusable cards, modals, charts, grids, and feedback · `frontend/src/components/SlotGrid.js`

### Backend

Flask API, services, and database

- [App factory](https://github.com/deveshjha-00/its/blob/main/backend/app/__init__.py): Flask bootstrap · Creates the Flask app and wires core runtime pieces · `backend/app/__init__.py`
- [Public API](https://github.com/deveshjha-00/its/blob/main/backend/app/routes/public.py): routes · Driver-facing HTTP endpoints · `backend/app/routes/public.py`
- [Admin API](https://github.com/deveshjha-00/its/blob/main/backend/app/routes/admin.py): routes · Privileged admin endpoints and auth · `backend/app/routes/admin.py`
- [Booking svc](https://github.com/deveshjha-00/its/blob/main/backend/app/services/booking_service.py): service · Booking lifecycle and QR check-in/out rules · `backend/app/services/booking_service.py`
- [Slot svc](https://github.com/deveshjha-00/its/blob/main/backend/app/services/slot_service.py): service · Slot state transitions and availability logic · `backend/app/services/slot_service.py`
- [Analytics svc](https://github.com/deveshjha-00/its/blob/main/backend/app/services/analytics_service.py): service · Dashboard aggregation and utilization data · `backend/app/services/analytics_service.py`
- [Prediction svc](https://github.com/deveshjha-00/its/blob/main/backend/app/services/prediction_service.py): service · Peak-hour prediction logic · `backend/app/services/prediction_service.py`
- [Domain models](https://github.com/deveshjha-00/its/blob/main/backend/app/models/booking.py): models · Slot, booking, and occupancy history shapes · `backend/app/models/booking.py`
- [DB layer](https://github.com/deveshjha-00/its/blob/main/backend/app/db/init.py): sqlite helpers · Schema init, seeding, and database path helpers · `backend/app/db/init.py`
- [Auto release](https://github.com/deveshjha-00/its/blob/main/backend/app/jobs/auto_release.py): background job · Scheduled expiry of unclaimed reservations · `backend/app/jobs/auto_release.py`

### Delivery

Container and CI tooling

- [CI pipeline](https://github.com/deveshjha-00/its/tree/main/Jenkinsfile): delivery · Jenkins-based build and validation automation · `Jenkinsfile`
- [Container](https://github.com/deveshjha-00/its/tree/main/dockerfile): deploy spec · Container build and runtime packaging · `dockerfile`

## Connections

- App shell → Driver page: routes · App shell renders the driver experience
- App shell → Admin page: routes · App shell renders the admin experience
- App shell → Landing: routes · App shell renders the entry screen
- Driver page → API client: calls · Driver actions go through the shared API client
- Admin page → API client: calls · Admin actions go through the shared API client
- Driver page → UI kit: uses · Driver UI is built from shared components
- Admin page → UI kit: uses · Admin UI is built from shared components
- API client → Public API: HTTP · Frontend talks to the public API boundary
- API client → Admin API: HTTP · Frontend talks to the admin API boundary
- App factory → Public API: registers · App factory wires public routes
- App factory → Admin API: registers · App factory wires admin routes
- App factory → Auto release: starts · App factory starts scheduled cleanup inside the backend process
- Public API → Booking svc: uses · Public endpoints delegate booking actions to services
- Public API → Slot svc: uses · Public endpoints delegate slot reads and updates to services
- Public API → Prediction svc: uses · Public endpoints expose peak-hour prediction
- Admin API → Analytics svc: uses · Admin endpoints serve dashboard analytics
- Admin API → Slot svc: uses · Admin endpoints force-release and update slots
- Booking svc → Domain models: reads/writes · Booking logic operates on domain models
- Slot svc → Domain models: reads/writes · Slot logic operates on domain models
- Analytics svc → Domain models: aggregates · Analytics are derived from persisted domain data
- Prediction svc → Domain models: analyzes · Prediction uses historical occupancy data
- Booking svc → DB layer: persists · Booking state is stored in SQLite
- Slot svc → DB layer: persists · Slot state is stored in SQLite
- Analytics svc → DB layer: reads · Analytics read from the database layer
- Auto release → Booking svc: expires · Background job marks stale reservations as expired
- Auto release → Slot svc: reclaims · Background job returns slots to available state
- CI pipeline → Container: builds · CI validates containerized delivery
- CI pipeline → App factory: tests · Pipeline covers backend runtime assembly
- CI pipeline → App shell: tests · Pipeline covers frontend build entry