LAFAEKSTREET - COMPLETE SYSTEM DIAGRAMS
System Architecture Diagram
Editable source: LafaekStreet_Architecture.drawio
SYSTEM OVERVIEW - 4 SEPARATE APPLICATIONS
LafaekStreet is composed of 4 independent applications, each serving different user groups:
| Application | Technology | Backend | Users | Purpose |
|---|---|---|---|---|
| Citizen Mobile App | Flutter (iOS/Android) | FastAPI (Python) | Citizens | Submit road infrastructure reports |
| Admin Panel | Next.js | Next.js API Routes | Administrators | Manage system, users, moderate reports (Local only) |
| Government Portal | Next.js | Next.js API Routes | Government Officials | Review & process reports, assign work |
| Public Dashboard | Next.js | Next.js API Routes | Everyone | View all public reports, statistics, map |
1. HIGH-LEVEL SYSTEM ARCHITECTURE
2. APPLICATION ARCHITECTURE BREAKDOWN
2.1 Citizen Mobile App (Flutter + FastAPI)
2.2 Admin Panel (Next.js - Local Only)
2.3 Government Portal (Next.js)
2.4 Public Dashboard (Next.js)
3. DATA FLOW - COMPLETE SYSTEM
4. USER AUTHENTICATION FLOWS
4.1 Citizen App Authentication (Google OAuth + Email/OTP)
4.2 Admin Panel Authentication (Local Only)
4.3 Government Portal Authentication (Email + Password + hCaptcha + Email 2FA)
5. REPORT LIFECYCLE ACROSS APPLICATIONS
6. MOBILE APP SCREEN FLOW (Flutter)
Offline Mode Flow
7. AI ANALYSIS PIPELINE
8. BLOCKCHAIN INTEGRATION (Hedera HCS)
What Gets Recorded on Blockchain
| Event | Data Recorded | When |
|---|---|---|
| Report Submission | report_number, issue_type, severity, GPS location | On create (background) |
| Status Change | New status, changed_by, timestamp | On status update |
| AI Validation | AI severity, confidence, damage type | After AI analysis |
9. ADMIN PANEL WORKFLOW
10. GOVERNMENT PORTAL WORKFLOW
11. PUBLIC DASHBOARD FEATURES
12. DATABASE SCHEMA OVERVIEW
13. NOTIFICATION SYSTEM
14. SECURITY ARCHITECTURE
Mobile App Security
15. DEPLOYMENT ARCHITECTURE
16. VALKEY CACHE STRATEGY
17. FASTAPI BACKEND - ENDPOINT ARCHITECTURE
SUMMARY
Total Applications: 4
| # | Application | Stack | Backend | URL | Primary Users |
|---|---|---|---|---|---|
| 1 | Citizen Mobile App | Flutter + Provider | FastAPI (Python) - 38 endpoints | api.lafaekstreet.com | Citizens |
| 2 | Admin Panel | Next.js 15 + Prisma | Next.js API Routes | localhost:3002 | Administrators |
| 3 | Government Portal | Next.js 14 + Prisma | Next.js API Routes | gov.lafaekstreet.com | Government Agencies |
| 4 | Public Dashboard | Next.js 14 + Prisma + LangChain + Nova 2 Lite | Next.js API Routes (Read-Only + AI Chat) | www.lafaekstreet.com | Everyone |
Shared Infrastructure:
- PostgreSQL 15+ (Aiven) - PostGIS + pgvector, shared by all 4 apps
- Valkey (Aiven) - Caching, sessions, rate limiting (FastAPI backend only)
- AWS S3 - Image storage (max 1 per report, 10MB each)
- AWS KMS - SECP256K1 hardware-backed signing (FastAPI backend only)
- SMTP (Gmail) - OTP email delivery via aiosmtplib (backend) + nodemailer (gov portal 2FA)
- Amazon Bedrock - Nova 2 Lite (backend AI analysis + dashboard chat) + Nova 2 Multimodal Embeddings (1024-dim vectors)
- LangChain - AI pipeline framework for RuaLafaek chat assistant (dashboard only)
- hCaptcha - Bot protection for public dashboard chat + gov portal login
- Hedera HCS - Immutable blockchain records (FastAPI backend only)
KEY ARCHITECTURE DECISIONS
Separation of Concerns:
- FastAPI handles citizen report submission (38 endpoints) with background processing
- Next.js apps handle admin, government, and public views via Prisma direct DB access
- Each app has its own backend logic
Security by Design:
- Admin Panel runs locally only (no external access)
- Government Portal has agency-level authentication
- Public Dashboard is read-only
- Dedicated PostgreSQL API user (not postgres root)
- AWS KMS hardware-backed signing (no private keys in code)
- JWT with access tokens (60 min) + long-lived refresh (30 days)
Offline-First Mobile:
- Hive NoSQL database for offline report storage
- OpenStreetMap tile caching for offline maps
- Automatic sync with connectivity monitoring
- GPS works without internet
- 100MB local storage limit with monitoring
Background Processing:
- Report creation returns immediately (201 Created)
- AI image relevance validation runs first — irrelevant images auto-reject and stop all further processing
- If relevant: AI damage analysis, blockchain submission, and vector embeddings run in background
- Citizens notified when AI assessment completes or when report is auto-rejected
Shared Database:
- All apps connect to the same PostgreSQL instance (Aiven)
- FastAPI uses SQLAlchemy 2.0 async ORM + Valkey cache
- Next.js apps use Prisma ORM for direct DB access (no cache layer)
Independent Deployment:
- Each app can be updated independently
- Different scaling requirements per app
- Fault isolation between applications
Complete system architecture with 4 separate applications, 38 API endpoints, and full blockchain + AI integration.