How deveshjha-00/its works
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: public.py Public API · slot_service.py Slot svc · App.js App shell · __init__.py App factory
Components 18
Frontend
Browser UI for drivers and admins
- App shell · Top-level browser app and route composition
frontend/src/App.js - API client · Central frontend boundary for backend requests
frontend/src/api/client.js - Driver page · Driver-facing booking, QR, and slot flow
frontend/src/pages/DriverPage.js - Admin page · Admin analytics, slot control, and logs
frontend/src/pages/AdminPage.js - Landing · Entry screen for the demo
frontend/src/pages/Landing.js - UI kit · Reusable cards, modals, charts, grids, and feedback
frontend/src/components/SlotGrid.js
Backend
Flask API, services, and database
- App factory · Creates the Flask app and wires core runtime pieces
backend/app/__init__.py - Public API · Driver-facing HTTP endpoints
backend/app/routes/public.py - Admin API · Privileged admin endpoints and auth
backend/app/routes/admin.py - Booking svc · Booking lifecycle and QR check-in/out rules
backend/app/services/booking_service.py - Slot svc · Slot state transitions and availability logic
backend/app/services/slot_service.py - Analytics svc · Dashboard aggregation and utilization data
backend/app/services/analytics_service.py - Prediction svc · Peak-hour prediction logic
backend/app/services/prediction_service.py - Domain models · Slot, booking, and occupancy history shapes
backend/app/models/booking.py - DB layer · Schema init, seeding, and database path helpers
backend/app/db/init.py - Auto release · Scheduled expiry of unclaimed reservations
backend/app/jobs/auto_release.py
Delivery
Container and CI tooling
- CI pipeline · Jenkins-based build and validation automation
Jenkinsfile - Container · Container build and runtime packaging
dockerfile
Connections 29
- 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