18. System Architecture Map — How Everything Connects¶

This document is the single reference showing every system in the KRG Digital Real Estate & Municipality Platform, which language powers it, and how they all connect.

18.1 Full Platform Overview¶

graph TD
  subgraph TOUCH["📱 Citizen Touchpoints"]
    direction LR
    MOB["📱 Mobile App<br/>Flutter 3.x (Dart)"]
    WEB["🌐 Web Portal<br/>Next.js 14+ (React)<br/>+ OpenLayers 9"]
    KIOSK["🏢 Service Center<br/>Flutter Kiosk (Dart)"]
  end

  subgraph AUTH["🔐 Identity Layer (Shared Gov)"]
    direction LR
    KRDPASS["KRDPASS (SSO)"] <-->|OIDC| KEYCLOAK["Keycloak<br/>OAuth 2.1 / RBAC"]
  end

  subgraph GW["🚪 API Gateway — Kong OSS"]
    direction LR
    RL["Rate Limiting"] ~~~ JWT["JWT Validation"] ~~~ ROUTE["Request Routing"]
    MTLS["mTLS Termination"] ~~~ IPWL["IP Allowlisting"] ~~~ CACHE["Response Caching"]
  end

  subgraph LARAVEL["🐘 PHP 8.4 / Laravel 13"]
    direction LR
    PROPSVC["Property<br/>Registration"]
    XFRSVC["Transfer<br/>Service"]
    PERMSVC["Building<br/>Permits"]
    VALSVC["Valuation<br/>Service"]
    PAYSVC["Payment<br/>Service"]
    MUNSVC["Municipal<br/>Service"]
    RENTSVC["Rental<br/>Registry"]
    APTSVC["Appointment<br/>Service"]
  end

  subgraph PYTHON["🐍 Python 3.12 / FastAPI"]
    direction LR
    DOCSVC["Document<br/>/ OCR"]
    GISSVC["GIS Service<br/>+ GeoServer"]
    ANASVC["Analytics<br/>/ ML"]
  end

  subgraph GOSVC["🔷 Go 1.22 / Gin"]
    AUDIT["Audit Service<br/>50K+ events/sec immutable logs"]
  end

  subgraph KAFKA["🔗 Apache Kafka (KRaft)"]
    direction LR
    T1["property.events"] ~~~ T2["transfer.events"] ~~~ T3["payment.events"]
    T4["permit.events"] ~~~ T5["document.events"] ~~~ T6["audit.events"]
  end

  subgraph KRGROAD["🏛️ KRG-Road (Shared Gov)"]
    direction LR
    SS_RE["Security Server<br/>(RE Platform)"]
    SSC["Security Server<br/>(Civil Status)"]
    SST["Security Server<br/>(Tax)"]
    SSN["Security Server<br/>(Notary)"]
    CENTRAL["Central Services<br/>Registry · Trust · Audit"]
  end

  subgraph DATA["💾 Data Layer"]
    direction LR
    PG["PostgreSQL 16<br/>+ PostGIS 3.4<br/>(Patroni)"]
    RDS["Redis 7<br/>Cluster"]
    MINIO["MinIO<br/>(S3)"]
    MEILI["Meilisearch"]
    GEO["GeoServer<br/>+ pg_tileserv"]
  end

  subgraph OBS["📊 Observability"]
    direction LR
    PROM["Prometheus<br/>+ Thanos"]
    LOKI["Loki<br/>+ Fluent Bit"]
    JAEG["Jaeger /<br/>Tempo"]
    GRAF["Grafana"]
    UKUMA["Uptime Kuma"]
    ALERTM["Alertmanager<br/>→ Telegram"]
  end

  subgraph SEC["🔒 Security Perimeter"]
    direction LR
    DDOS["DDoS<br/>Arbor"] --> FW["pfSense<br/>FW"] --> WAF["WAF<br/>ModSecurity"] --> ISTIO["Istio<br/>Mesh"]
    WAZUH["Wazuh SIEM"] ~~~ SURI["Suricata"] ~~~ CROW["CrowdSec"] ~~~ VAULT["Vault"]
  end

  subgraph INFRA["🏗️ Infrastructure"]
    direction LR
    SUL["Sulaymaniyah DC<br/>(Primary)<br/>Rocky Linux 9 + RKE2"]
    EBL["Erbil DC<br/>(DR)<br/>Rocky Linux 9 + RKE2"]
    SUL <-->|Dedicated Fiber| EBL
  end

  TOUCH --> AUTH --> GW
  GW --> LARAVEL
  GW --> PYTHON
  GW --> GOSVC
  LARAVEL --> KAFKA
  PYTHON --> KAFKA
  GOSVC --> KAFKA
  LARAVEL --> DATA
  PYTHON --> DATA
  KAFKA --> KRGROAD
  DATA --> OBS
  OBS --> SEC
  SEC --> INFRA

18.2 Service-to-Language Map (Quick Reference)¶

18.3 How a Property Transfer Flows (End-to-End)¶

sequenceDiagram
    autonumber
    participant C as 👤 Property Owner
    participant APP as 📱 Flutter / Next.js
    participant KONG as 🚪 Kong Gateway
    participant XFR as 🐘 Transfer Service
    participant ROAD as 🏛️ KRG-Road
    participant DB as 💾 PostgreSQL + PostGIS
    participant KAFKA as 📨 Apache Kafka
    participant PAY as 💳 Payment Service
    participant AUDIT as 🔷 Audit (Go)
    participant NOTIF as 🔔 Notification

    C->>APP: Submit transfer request (buyer, property, price)
    APP->>KONG: HTTPS + JWT
    KONG->>XFR: Route to Transfer Service
    XFR->>DB: Create transaction record (status: initiated)
    XFR->>ROAD: Query Civil Status (verify buyer identity)
    ROAD-->>XFR: Identity confirmed ✓
    XFR->>ROAD: Query Tax Authority (no outstanding debt?)
    ROAD-->>XFR: Tax clearance ✓
    XFR->>DB: Check encumbrances (mortgages, liens)
    DB-->>XFR: No active encumbrances ✓
    XFR->>KAFKA: Publish transfer.initiated
    XFR-->>APP: Application submitted — awaiting review
    Note over XFR: Staff reviews in Filament admin
    XFR->>PAY: Calculate & collect transfer tax + fees
    PAY-->>XFR: Payment confirmed
    XFR->>DB: Update ownership_records + ownership_history
    XFR->>KAFKA: Publish transfer.completed
    KAFKA->>AUDIT: Log immutably (hash chain)
    KAFKA->>NOTIF: SMS + Push to buyer & seller
    NOTIF->>C: 🎉 "Transfer registered — new deed available"

18.4 External Integration Flow (via KRG-Road)¶

graph TD
  CIT["👤 Citizen requests<br/>property transfer"] --> KONG["🚪 Kong Gateway"]
  KONG --> ENGINE["⚙️ Transfer Service<br/>(Laravel 13 — PHP 8.4)<br/>Needs data from 3 sources"]

  ENGINE -->|KRG-Road<br/>mTLS + signed| SSC["🔐 Security Server<br/>(Civil Status)"]
  ENGINE -->|KRG-Road<br/>mTLS + signed| SST["🔐 Security Server<br/>(Tax Authority)"]
  ENGINE -->|KRG-Road<br/>mTLS + signed| SSN["🔐 Security Server<br/>(Notary)"]

  SSC --> CIVIL["👤 Civil Status<br/>Registry"]
  SST --> TAX["💰 Tax<br/>System"]
  SSN --> NOTARY["📜 Notary<br/>Records"]

  CIVIL -->|Identity verified ✓| RESULT["⚙️ Transfer Service<br/>compiles results"]
  TAX -->|No debt ✓| RESULT
  NOTARY -->|Power of attorney valid ✓| RESULT

  RESULT --> PAY["💳 Payment<br/>(Laravel)"]
  RESULT --> DIGSIG["🔏 Digital Sig<br/>(EJBCA)"]
  RESULT --> DOC["📄 Doc Vault<br/>(MinIO)"]
  RESULT --> NOTIFY["🔔 Notify"]
  RESULT --> AUDIT2["📝 Audit<br/>(Go)"]

18.5 Language Boundary Rules¶

18.6 Port/Protocol Map¶

18.7 Deployment Topology (Kubernetes)¶

graph LR
  CLUSTER["☸️ RKE2 Kubernetes<br/>Sulaymaniyah DC"]

  subgraph NS1["re-gateway"]
    KONG2["Kong (3 replicas, HPA)"]
  end
  subgraph NS2["re-laravel"]
    L1["property-registration (3)"]
    L2["transfer-service (3)"]
    L3["building-permits (2)"]
    L4["valuation-service (2)"]
    L5["payment-service (3)"]
    L6["municipal-service (2)"]
    L7["rental-registry (2)"]
    L8["appointment-service (2)"]
    L9["filament-admin (2)"]
  end
  subgraph NS3["re-python"]
    P1["document-ocr-service (2)"]
    P2["gis-service (2)"]
    P3["analytics-ml-service (2)"]
  end
  subgraph NS4["re-go"]
    G1["audit-service (3, high IOPS)"]
  end
  subgraph NS5["re-data"]
    D1["PostgreSQL + PostGIS Patroni (3)"]
    D2["Redis Sentinel (3)"]
    D3["Kafka KRaft (3)"]
    D4["MinIO (4, erasure)"]
    D5["Meilisearch (2)"]
    D6["Schema Registry (2)"]
  end
  subgraph NS6["re-geo"]
    GS1["GeoServer (2)"]
    GS2["pg_tileserv (2)"]
  end
  subgraph NS7["re-auth"]
    A1["Keycloak (3, shared)"]
    A2["EJBCA (2, shared)"]
  end
  subgraph NS8["re-interop"]
    I1["Security Server (RE)"]
  end
  subgraph NS9["re-observability"]
    O1["Prometheus + Thanos"]
    O2["Loki + Fluent Bit"]
    O3["Grafana"]
    O4["Jaeger / Tempo"]
    O5["Uptime Kuma"]
    O6["Alertmanager"]
  end
  subgraph NS10["re-security"]
    S1["Wazuh + Elasticsearch"]
    S2["Suricata"]
    S3["CrowdSec"]
    S4["OPA / Gatekeeper"]
  end
  subgraph NS11["re-devops"]
    DV1["GitLab CE"]
    DV2["ArgoCD"]
    DV3["Harbor"]
    DV4["SonarQube"]
    DV5["HashiCorp Vault"]
  end

  CLUSTER --> NS1
  CLUSTER --> NS2
  CLUSTER --> NS3
  CLUSTER --> NS4
  CLUSTER --> NS5
  CLUSTER --> NS6
  CLUSTER --> NS7
  CLUSTER --> NS8
  CLUSTER --> NS9
  CLUSTER --> NS10
  CLUSTER --> NS11

18.8 Technology Count Summary¶