Modern Thin-Client Ecosystem
Decoupling client presentations from mission-critical business logic. A single heavy centralized RESTful server powers lightweight thin clients across Web and Android with zero direct database exposure.
Encapsulates all processing, business rules, authorization, and state management. Keeps client devices lightweight and ensures uniform behavior across platforms.
The Centralized Server (The "Heavy" Backend)
Single authoritative brain for authentication, security validation, and database operations🛡️ Roles & Responsibilities
- Authentication & Sessions: Argon2id credential verification, edit session cookies, and JWT issuance.
- Zero Client DB Access: Clients only speak HTTP REST; database credentials never touch the browser or APK.
- Complex Calculations: Algorithmic 6-character Public ID generation (Stage 1/2), 13-character Edit ID generation, and GPS coordinates calculation.
- Immutability & Auditing: Immutable snapshot versioning on every address edit, access logs, and rate-limiting brute force protection.
⚡ Tech Stack & Storage Isolation
Built on Python (Flask & SQLAlchemy 2.x) with an isolated SQLite WAL / PostgreSQL backend.
📡 Centralized REST API Surface (Consumable by all Thin Clients)
| Method | Endpoint | Description | Thin Client Access |
|---|---|---|---|
| GET | /api/v1/resolve/{public_id} |
Resolves physical address, driving directions, reach scope, coordinates. | Public (No auth needed) |
| POST | /api/v1/addresses/direct-create |
Passwordless creation with parents' initials, CNIC ending, DOB -> Secret Edit ID. | Public (Mobile/Web) |
| POST | /api/v1/auth/edit-id-login |
Authenticates thin client via 13-character Edit ID. Returns session token. | Edit Portal Clients |
| GET | /api/v1/addresses |
Lists, searches, and filters user addresses with pagination and reach scopes. | Bearer Token Auth |
| GET | /api/v1/system/architecture |
Returns platform specs, active counts, and ecosystem paths telemetry. | Public Diagnostic |
| POST | /api/v1/system/simulate |
Simulates live Web or Android thin-client request execution and latency. | Ecosystem Visualizer |
The Thin Clients (The "Light" Frontends)
Frontends only make HTTP requests over the network and render the UI. Choose between three primary paths:Flutter / React Native
How it works: You write the client-side code once in Flutter (Dart) or React Native, and it compiles directly into both a lightweight Web App and a native Android App.
Keeps the client extremely light, avoids duplicating work across web and mobile, and both versions communicate seamlessly with your central API.
clients/path-a-cross-platform-flutter/
HTMX + Capacitor / Turbo
How it works: The central server sends fully rendered HTML instead of raw JSON. For Android, you wrap this responsive web app using tools like Capacitor or Turbo Native.
The client contains practically zero logic. Updating a feature on the central server instantly reflects across web and Android without requiring app store review updates.
clients/path-b-server-driven-ui/
React Web + Kotlin Android
How it works: You build the web app using a standard browser framework (React/Vue) and the Android app natively using Kotlin + Retrofit/Compose.
Offers the highest possible device integration and OS performance. However, requires maintaining two separate thin-client codebases talking to the central server.
clients/path-c-separate-native/