Skip to content

LAFAEKSTREET - COMPLETE SYSTEM DIAGRAMS ​


System Architecture Diagram ​

LafaekStreet Architecture

Editable source: LafaekStreet_Architecture.drawio


SYSTEM OVERVIEW - 4 SEPARATE APPLICATIONS ​

LafaekStreet is composed of 4 independent applications, each serving different user groups:

ApplicationTechnologyBackendUsersPurpose
Citizen Mobile AppFlutter (iOS/Android)FastAPI (Python)CitizensSubmit road infrastructure reports
Admin PanelNext.jsNext.js API RoutesAdministratorsManage system, users, moderate reports (Local only)
Government PortalNext.jsNext.js API RoutesGovernment OfficialsReview & process reports, assign work
Public DashboardNext.jsNext.js API RoutesEveryoneView 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 ​

EventData RecordedWhen
Report Submissionreport_number, issue_type, severity, GPS locationOn create (background)
Status ChangeNew status, changed_by, timestampOn status update
AI ValidationAI severity, confidence, damage typeAfter 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

#ApplicationStackBackendURLPrimary Users
1Citizen Mobile AppFlutter + ProviderFastAPI (Python) - 38 endpointsapi.lafaekstreet.comCitizens
2Admin PanelNext.js 15 + PrismaNext.js API Routeslocalhost:3002Administrators
3Government PortalNext.js 14 + PrismaNext.js API Routesgov.lafaekstreet.comGovernment Agencies
4Public DashboardNext.js 14 + Prisma + LangChain + Nova 2 LiteNext.js API Routes (Read-Only + AI Chat)www.lafaekstreet.comEveryone

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 ​

  1. 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
  2. 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)
  3. 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
  4. 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
  5. 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)
  6. 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.

Built for Timor-Leste