Update README.md

README.md

@@ -9,34 +9,63 @@ app_file: app.py
 pinned: false
 ---
 
-# 🚦 SwiftCase.ai  
-### Smart Traffic Justice Platform
+# 🚦 SwiftCase.ai — Real-world Traffic Offence MVP
 
-SwiftCase.ai is an MVP platform that connects **citizens**, **traffic police**, and the **magistrate** to streamline traffic fine and accident case handling.  
-The system reduces backlog, allows digital appeals, and provides the magistrate with time to review cases before hearings.  
+SwiftCase.ai is a Minimum Viable Product (MVP) to streamline traffic offence handling between **citizens**, **PDRM (traffic police)** and the **magistrate / online judge**. This MVP supports:
+
+- Digital **compound payments** to PDRM.
+- **PDRM compound appeals** (rayuan kompaun) reviewed online by police officers (BM logs).
+- **Judicial appeals** to Magistrate (human or AI with authority consent).
+- Full **audit trail** (immutable logs) and digital receipts for PDRM payments.
 
 ---
 
-## ✨ Features
+## Key Features (real-world oriented)
+
+- **Citizen Portal** (all labels/messages shown in 3 languages simultaneously):
+  - View case details (EN / BM / ZH)
+  - Pay compound (simulate PDRM payment)
+  - Submit **PDRM compound appeal** (Rayuan Kompaun — Bahasa Melayu)
+  - Submit **Judicial appeal** to Magistrate (EN/BM/ZH fields)
+  - View audit logs
 
-- **Citizen Portal**  
-  - View traffic cases by ID  
-  - Pay fines digitally  
-  - Submit appeals with supporting evidence  
-  - 🧓 Friendly to all Malaysians: **Every label, button, and message is shown in 3 languages at once**  
-    - English  
-    - Bahasa Melayu  
-    - 中文 (Chinese)  
+- **PDRM (Police) Portal** — **Bahasa Melayu only**:
+  - Create new summons/case (structured fields reflect real PDRM ticket)
+  - See pending PDRM appeals and decide (tolak / dikurangkan)
+  - Decisions and payment receipts logged in **Bahasa Melayu**
 
-- **Traffic Police Portal**  
-  - Create new cases with citizen details, fines, and evidence uploads  
-  - Interface shown in **Bahasa Melayu only** 🇲🇾  
+- **Magistrate Portal**:
+  - Review pending judicial appeals
+  - Record decisions (Approve No Fine / Approve Reduced / Reject)
+  - Record reviewer type (human_judge / ai_agent) and authority consent when AI is used
 
-- **Magistrate Portal**  
-  - Review appealed cases in a dashboard  
-  - Decide: Approve Appeal / Reject Appeal / Escalate Hearing  
-  - Interface available in **English or Bahasa Melayu**  
+- **Data & Audit**:
+  - SQLite schema includes `summons_cases`, `appeals`, `judge_reviews`, `pdrm_reviews`, `payments`, `receipts`, and `audit_logs`.
+  - PDRM-related logs/messages are recorded in **Bahasa Melayu** per requirement.
+  - Seeded demo data includes 3 fictitious cases (Ali, Ah Kow, Muthu) with tri-lingual descriptions.
 
 ---
 
+## How it works (flow)
+
+1. **PDRM issues summons** → data stored in `summons_cases`.
+2. **Citizen**:
+   - Can **Pay Compound** immediately (payable amount stored in case).
+   - Or **Appeal to PDRM** for a reduced compound (handled by police portal).
+   - Or **Appeal to Magistrate** (judicial path).
+3. **PDRM Officer** (Police Portal) decides on compound appeal:
+   - If **tolak** → payable stays standard RM300.
+   - If **dikurangkan** → payable updated to reduced amount.
+   - PDRM issues a digital receipt upon successful payment.
+   - All PDRM logs are written in **Bahasa Melayu**.
+4. **Magistrate** reviews judicial appeals and issues decisions; decisions update payable amounts and are logged.
+5. **Citizen pays** after decision; payment & receipts saved.
+
+---
+
+## Quick start (local / Hugging Face)
+
+### Requirements
+- Python 3.10+
+- Dependencies in `requirements.txt` (Gradio, pandas). Use `gradio==5.44.1` for compatibility.