π Fail MD
π api-spec.md
π architecture.md
π compound-rules.md
π council-sync.md
π data-model.md
π money-ledger.md
π parking-rules.md
Sedang mengedit: architecture.md
# Smart Parking β System Architecture This document captures the overall architecture and the latest agreed decisions. > Companion docs in this folder: > - `data-model.md` β tables, `tenant_id`, relationships > - `money-ledger.md` β wallet, liability, reserve, settlement, refund, reconciliation > - `parking-rules.md` β charging windows, rest time, public holiday, sessions, extend > - `compound-rules.md` β compound types, rates, enforcement > - `council-sync.md` β push to councils, data scope > - `api-spec.md` β REST endpoints ## Components | Component | Role | |---|---| | **Website** | Standalone info website. Not connected to the system. | | **User App** (Flutter) | Public users β start parking session, pay (wallet / FPX / card), pay compound, find empty bay via live map. | | **Staff Scanner** (Flutter) | Staff β scan plate (manual or OCR/LPR) to check if paid; if not, issue compound. | | **Staff Parking** (Flutter) | Staff β check & pay compound only (no walk-in new parking). | | **Backend** (Node) | REST API, IoT Ingestion, Payment Webhook, Wallet/Ledger Service, Admin-Operator, Notification, Council Sync. | | **Database** | MySQL with replication β Primary (write) + Replica (read). Hosted on AWS EC2. | | **Payment Gateway** | Razer / Chip Asia (FPX, Card, E-Wallet, etc.). | | **IoT Layer** | Street parking sensors β LoRaWAN gateway/network server (Celcom/Digi). Info only, no money. | | **Councils (tenants)** | MBPP (Pulau Pinang) & MBSP (Seberang Perai) β each with local DB; backend pushes data to them. | ## Build Order `backend` β `user-app` β `staff-scanner` β `staff-parking` β `website` ## Tech Stack - **Backend:** Node - **Database:** MySQL (Primary/Replica) on AWS EC2 - **Mobile apps:** Flutter - **Payment gateways:** Razer, Chip Asia - **IoT transport:** LoRaWAN (Celcom/Digi), ingestion via webhook/MQTT - **Notifications:** SMS + Email (users), Telegram (IT team) --- ## High-Level Architecture (Mermaid) ```mermaid flowchart TD Website["π Website (info, standalone)"] subgraph Clients["Apps (Flutter)"] UserApp["π± User App<br/>session + pay (wallet / FPX / card)<br/>pay compound + find empty bay"] Scanner["π² Staff Scanner<br/>check paid? + issue compound"] Parking["π’ Staff Parking<br/>check + pay compound"] end subgraph IoT["π‘ IoT Layer (info only β no money)"] Sensor["Parking Sensors<br/>(empty / occupied)"] LoRa["LoRaWAN Gateway + Network Server<br/>(Celcom / Digi)"] Sensor --> LoRa end subgraph BE["βοΈ BACKEND (Node, multi-tenant)"] API["REST API"] Ingest["IoT Ingestion"] Webhook["Payment Webhook"] Ledger["Wallet / Ledger Service"] Admin["Admin-Operator<br/>(role + tenant filtered)"] Notif["Notification"] Sync["π Council Sync"] end subgraph DBC["ποΈ MySQL (Replication) β AWS EC2"] Primary[("Primary (write)")] Replica[("Replica (read)")] Primary -->|replicate| Replica end Pay["π³ Payment Gateway<br/>(Razer / Chip Asia)"] Maps["πΊοΈ Maps (Google / Waze)"] subgraph Councils["ποΈ Councils (tenants)"] MBPP["MBPP + local DB"] MBSP["MBSP + local DB"] end UserApp --> API Scanner --> API Parking --> API UserApp -. live map .-> Maps LoRa -->|uplink| Ingest API --> Admin API --> Ledger API --> Notif API -->|write| Primary API -->|read| Replica Ingest -->|update bay status| Primary Ledger -->|write| Primary Admin -->|read| Replica UserApp -->|top-up / pay| Pay Parking -->|pay compound| Pay Pay -->|callback| Webhook Webhook --> Ledger Notif -->|SMS / Email| UserApp Notif -.->|Telegram| IT["π¨βπ» IT Team"] Sync -->|push| MBPP Sync -->|push| MBSP Sync --> Replica ``` --- ## Detailed Backend Flow (Mermaid) Internal flow of the core backend processes (auth/tenant filter, parking, enforcement, money, IoT, sync). ```mermaid flowchart TD subgraph Entry["Entry"] Req["Incoming Request<br/>(app / webhook / uplink)"] Auth["Auth + Tenant Resolver<br/>(role + tenant_id scope)"] Req --> Auth end Auth --> Router{"Request type?"} %% Parking flow Router -->|Start Parking| P1["Validate plate + user"] P1 --> P2["Check time rules<br/>(charging window / rest / holiday)"] P2 --> P3["Compute fee + end_at<br/>(skip rest, daily max)"] P3 --> P4{"Pay method"} P4 -->|E-Wallet| P5["Deduct wallet balance<br/>(liability to revenue)"] P4 -->|FPX / Card| P6["Gateway charge<br/>(direct to revenue)"] P5 --> P7["Create session<br/>(tenant_id, start, end)"] P6 --> P7 P7 --> LED[(Ledger entry)] P7 --> NOTIF["Notify user (SMS/Email)"] %% Scanner / enforcement flow Router -->|Scan Plate| S1["Lookup active session<br/>plate + staff.tenant_id"] S1 --> S2{"Valid and not expired?"} S2 -->|Yes| S3["π’ PAID"] S2 -->|No| S4["π΄ NOT PAID"] S4 --> S5{"Issue compound?<br/>(staff discretion / illegal)"} S5 -->|Yes| S6["Create compound<br/>(type, rate, tenant_id)"] S5 -->|No| S7["Skip"] S6 --> LED S6 --> NOTIF %% Compound payment Router -->|Pay Compound| C1["Lookup compound"] C1 --> C2{"Pay method"} C2 -->|E-Wallet| C3["Deduct wallet"] C2 -->|FPX / Card| C4["Gateway charge"] C3 --> C5["Mark compound PAID"] C4 --> C5 C5 --> LED %% Money / settlement Router -->|Top-up| M1["Gateway charge"] M1 --> M2["Wallet balance +<br/>(liability)"] M2 --> LED Router -->|Refund| R1["Refund wallet balance only"] R1 --> LED LED --> SET["Settlement engine<br/>commission(per tenant) + reserve<br/>+ payout per tenant"] SET --> RECON["Reconciliation<br/>bank = liability + reserve<br/>+ unsettled + unreleased commission"] %% IoT Router -->|Sensor Uplink| I1["Decode payload"] I1 --> I2["Update bay status<br/>(empty/occupied, tenant_id)"] I2 --> I3["Aggregate area occupancy (e.g. 20/26)"] %% Sync LED -. scheduled .-> SY1["Council Sync<br/>push revenue/compounds/<br/>vehicles/users (per tenant)"] SY1 --> MBPP[("MBPP local DB")] SY1 --> MBSP[("MBSP local DB")] ``` --- ## Backend Sidebar Menu (ASCII) ``` βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β SMART PARKING β BACKEND β β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ β β β π Dashboard β β β β π ΏοΈ Parking β β βββ Parking Sessions (active / history) β β βββ Zones / Locations β β βββ Rates / Pricing (per tenant) β β β β π« Compounds (Saman) β β βββ Compound List β β βββ Compound Payments β β βββ Compound Types (unpaid / illegal ...) β β βββ Compound Rates (per tenant) β β β β π‘ Devices (IoT) β β βββ Device List (sensor + empty/occupied) β β βββ Add / Register Device β β βββ Gateways (LoRaWAN β Company A) β β βββ Device Health (battery, signal, last seen) β β βββ Uplink Logs (raw data β debug) β β β β π° Finance β β βββ Revenue β β βββ Wallet / Liability β Company A β β βββ Ledger β β βββ Top-ups & Payments β β βββ Refunds (wallet balance only) β β βββ Settlement / Payout β β βββ Reserve (rolling) β Company A β β βββ Commission (per tenant) β Company A β β βββ Reconciliation β Company A β β β β π Reports β β βββ Revenue Report β β βββ Float / Liability Report β Company A β β βββ Monthly Statement β β β β βοΈ Settings β β β β β βββ Global Config β β β βββ General β β β βββ Branding β β β βββ Backup & Restore β β β βββ Maintenance & Cache β β β β β βββ Integration β β β βββ API & Webhook β β β βββ Weather β β β βββ Maps β β β βββ Telegram β β β βββ Email (SMTP) β β β βββ SMS β β β βββ Recycle Bin β β β βββ Public Holiday β β β β β βββ Roles Management β β β β β βββ User Management β β β [tabs: Administrator | Staff | User] β β β β β βββ Tenant β Company A β β β [tabs: Tenant | Commission Settings] β β β β β βββ Logs β β [tabs: Activity Log | Audit Log] β β β β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ β β Company A = central operator only (hidden from tenants)β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ ``` --- ## Key Decisions (summary β see detail docs for full rules) ### Multi-Tenant (`tenant_id`) - **Company A** = central operator; owns/runs system, holds all funds, takes commission, settles to councils. Sees everything. - **MBPP & MBSP** = tenants; see only their own data. - `tenant_id` is mandatory on almost every table: sessions, compounds, devices, zones, rates, staff, revenue, payouts, ledger. - **Public users** = global accounts; `tenant_id` set per transaction (by parking location). - **Wallet balance** = global liability; ledger entries get `tenant_id` only when money is spent. - **Staff** = `tenant_id` fixed on the account. ### Payment & Time-Based Parking - Time-based (e.g. 6h), not tied to a bay. Valid within ONE tenant only. - Pay method chosen in-app: **E-Wallet** OR **direct** (FPX / Card / saved card). - **Charging windows per tenant** (e.g. 08:00-12:00, 13:30-17:00). Rest time between windows is skipped (timer pauses); there is a **daily max chargeable** (sum of windows). - **Clock-time within a window** (start 9:11:00 + 1h β ends 10:11:00; valid while `now < end_at`). - **Public Holiday** = free all day; paying is blocked ("Free Parking on Public Holiday"). - **Rest Time** = temporary free; user may opt to start paying at next window ("Free Parking for Rest Time"). - **Extend** is supported by the backend data model (button lives in user-app). ### Scanner / Enforcement - Scanner checks by **plate + staff.tenant_id**: active paid session for this tenant? If not β may issue compound. - Plate entry: **manual typing or OCR/LPR**. - **No tolerance / grace period.** ### Compounds (Saman) - **Multiple types** (extensible), e.g.: - `UNPAID_PARKING` β in a paid bay with no active session (staff discretion to skip). - `ILLEGAL_PARKING` β yellow line / roadside / traffic offence (issue regardless of payment). - Stamped with the **staff's `tenant_id`**. Has its own **rate per tenant**. - Payable via **User App** or **walk-in council** (Staff Parking app). - Repeated compounds allowed. ### Users & Vehicles - **Registration mandatory** (prevents credit-card misuse). - **User β Vehicle = many-to-many**; limits set per tenant (e.g. 1 user β 5 vehicles, 1 vehicle β 5 users). ### Sensors (IoT) β info only - Detect empty/occupied per bay; no money link. - Aggregate occupancy per area (e.g. "20/26"). Powers User App live map β tap β navigate. ### Money Model - All payments flow through gateway β **Company A single bank account** (pooled). Split is logical (ledger). - **Gateway fees** deducted before recognizing real revenue. - **Commission differs per tenant** (MBPP β MBSP). - **Wallet float/liability** = top-up not yet spent; user's money; stays in account; does NOT leave at settlement; carried forward. - **Refund** = wallet balance only (parking time itself is non-refundable; pay 6h = 6h). - **Reserve (rolling)** = held from council share to cover refunds/chargebacks; carried forward; released when unused. - **Ledger is immutable**; balances computed from ledger (never stored as mutable number). - **Settlement** = transfer each council's recognized share from Company A to council bank account; timing follows gateway schedule (T+1 or live, depends). - **Reconciliation:** `bank = liability + reserve + unsettled revenue + unreleased commission` (diff should be 0). ### Council Sync - Backend **pushes** to each council's local DB: that council's compounds, payments, vehicles, related users (per tenant). - Councils need the data for **backup**; whether apps read from local DB or AWS EC2 is TBD (to be decided in council meeting). ### Notifications - Users: **SMS + Email**. IT team: **Telegram**. --- ## Open Items (TBD) 1. **Council Sync details** β read from local DB vs AWS EC2, frequency, offline handling. (council meeting) 2. **Pay during rest time** β confirmed: offer "start at next window"; needs UI detail in user-app. 3. **Wallet top-up min/max** β set per tenant; rule when wallet is global TBD (use the tenant of the transaction context).
Simpan Perubahan