FalahOS Architecture Diagram

flowchart TB
    %% Styles
    classDef user fill:#1e293b,stroke:#94a3b8,stroke-width:1.5
    classDef cf fill:#78350f,stroke:#fbbf24,stroke-width:1.5
    classDef frontend fill:#083344,stroke:#22d3ee,stroke-width:1.5
    classDef backend fill:#064e3b,stroke:#34d399,stroke-width:1.5
    classDef db fill:#4c1d95,stroke:#a78bfa,stroke-width:1.5
    classDef agent fill:#881337,stroke:#fb7185,stroke-width:1.5
    classDef external fill:#1e293b,stroke:#94a3b8,stroke-width:1.5
    classDef model fill:#78350f,stroke:#fb923c,stroke-width:1.5
    classDef swarm fill:#1e3a5f,stroke:#60a5fa,stroke-width:1.5
    classDef synergy fill:#3b0764,stroke:#c084fc,stroke-width:1.5

    %% ── Users / Channels ──
    subgraph USERS["Users & Channels"]
        direction LR
        TG["Telegram (DM + Ops Chat)"]
        WA["WhatsApp (+6013-225 0691)"]
        WB["Web Browser (falahos.my / ummah / git / auth)"]
    end

    %% ── Cloudflare Edge ──
    subgraph CF["Cloudflare Edge"]
        direction LR
        DNS["DNS (Proxied)"]
        WAF["WAF (Security Rules)"]
        TUN["cloudflared Tunnel"]
    end

    %% ═══════════════════════════════════════════════════
    %% DOCKER SWARM CLUSTER (Synology Manager + Contabo Worker)
    %% ═══════════════════════════════════════════════════
    subgraph SWARM["Docker Swarm Cluster"]
        direction LR

        subgraph SYNOLOGY["Synology NAS DS3617xs (100.126.73.29) — Swarm Manager"]
            direction TB

            ST1["Traefik v2 — Reverse Proxy (HTTPS routing)"]
            ST2["Gitea 1.26 — git.falahos.my (:3080)"]
            ST3["Casdoor — auth.falahos.my (Identity Provider)"]
            ST4["falah-mobile — Next.js frontend (falahos.my)"]
            ST5["falah-mobile-staging — Staging environment"]
            ST6["PostgreSQL 16 — Main application database"]
            ST7["Redis 7 — Cache layer"]
            ST8["Casdoor DB (Postgres 16) — Auth database"]

            %% Synology Standalone Containers
            SUB1["falah-umbrel stack: wallet / app / ramz / ummahid / istore / mocknet / carbon / faraid / halal / redis"]
            SUB2["Halal Monitor: postgrest + postgis + nginx"]
            SUB3["Karakeep: bookmarking + meilisearch + chrome"]
            SUB4["Mattermost: team chat + db"]
            SUB5["Garage S3: Object storage"]
            SUB6["Falah services: desktop / backend / UI / tunnel / mobile-staging"]
            SUB7["Portainer / Dockge x2 / Watchtower"]
            SUB8["Gitea Runners x3 — CI/CD"]
            SUB9["Linkstack / Affine / iStore / Identity-layer / Auth"]
            SUB10["Faraid-anvil: Foundry (blockchain dev)"]
        end

        subgraph CONTABO["Contabo VPS (13.140.161.244) — Swarm Worker + Edge"]
            CT1["Traefik Edge Node (:80 / :443)"]
            CT2["Hermes Agent — Primary orchestrator"]
            CT3["Hermes Gateway (Telegram / WhatsApp)"]
            CT4["FalahOS Relay — Telegram bus (:8088)"]
            CT5["SSH Tunnel (-> Mac Mini :17860)"]
            CT6["falah-auto-healer — Hourly health checks"]
            CT7["Cron jobs — Content pipeline / health monitoring"]
        end
    end

    %% ═══════════════════════════════════════════════════
    %% cPanel / WordPress
    %% ═══════════════════════════════════════════════════
    subgraph CP["cPanel Hosting — RoketServer (64.20.37.43)"]
        UMMAH["ummah.falahos.my WordPress + EDD + MailPoet + bbPress + GamiPress + Tutor LMS + falah-wallet + falah-souq + nur-ai-coach"]
        MY["my.falahos.my (monetisation subdomain)"]
        WPDB[("MySQL (WordPress DB)")]
    end

    %% ═══════════════════════════════════════════════════
    %% Agent Fleet (Tailscale)
    %% ═══════════════════════════════════════════════════
    subgraph TAILSCALE["Tailscale Mesh — Agent Fleet"]
        subgraph MACMINI["Mac Mini (100.72.2.115)"]
            ODY["Odysseus (:7860 — API / AI chat / email / research)"]
            PI2["Pi (:4747 — AI assistant)"]
            OH["OpenHand (:3000 — Coding agent)"]
            OCL["OpenClaw (:3100 — Model proxy)"]
            CC["Claude Code (CLI — Coding)"]
        end
        MBA["MacBook Air (100.76.3.26)\nopenclaw MCP (:18789) / hermes cron\npi / opencode / agy / claude"]
    end

    %% ═══════════════════════════════════════════════════
    %% External / GitHub
    %% ═══════════════════════════════════════════════════
    subgraph EXT["External & GitHub"]
        GH["GitHub (maifors)\n faraid-sandbox / falah-umbrel\n falah-extension / falah-os-sdk\n falah-mobile-staging / war-room mirror"]
        PP["PayPal Standard (wanjauhari@me.com)"]
        OCPROXY["OpenClaw Proxy (opencode.ai/zen)\nDeepSeek v4 / Qwen 3.6"]
        MCP["MCP Servers (UI/UX Tester)"]
    end

    %% ═══════════════════════════════════════════════════
    %% CONNECTIONS
    %% ═══════════════════════════════════════════════════

    %% Users → Cloudflare
    TG -.->|Gateway| CT3
    WA -.->|Gateway| CT3
    WB --> DNS
    DNS --> WAF
    WAF --> TUN

    %% Cloudflare → Swarm
    TUN --> ST1
    ST1 --> ST2
    ST1 --> ST3
    ST1 --> ST4
    ST1 --> ST5

    %% Cloudflare → cPanel
    TUN --> UMMAH
    TUN --> MY

    %% Synology → Contabo (Swarm internal)
    SYNOLOGY -.-|Swarm Join| CONTABO

    %% Contabo → Agent fleet
    CT4 -->|Relay| ODY
    CT4 -->|Relay| PI2
    CT4 -->|Relay| OH
    CT4 -->|Relay| OCL
    CT4 -->|Relay| CC
    CT4 -->|Relay| MBA
    CT5 -.->|SSH Port Forward| ODY

    %% Contabo → External
    CT2 -.->|CI-CD| ST2
    CT2 -.->|GitHub mirror| GH

    %% cPanel connections
    UMMAH --> WPDB
    MY --> WPDB
    UMMAH -.->|Payment| PP
    UMMAH -.->|Git Deploy| ST2

    %% Agent → OpenClaw proxy
    OCL -.->|API Calls| OCPROXY

    %% Synology internal
    SUB5 -.->|S3 API| ST4
    SUB3 -.->|Sync| ST2
    SUB8 -.->|Run Actions| ST2

    %% Assign classes
    class TG,WA,WB user
    class DNS,WAF,TUN cf
    class USERS,CF external
    class ST1,ST2,ST3,ST4,ST5 swarm
    class ST6,ST7,ST8 db
    class SUB1,SUB2,SUB3,SUB4,SUB5,SUB6,SUB7,SUB8,SUB9,SUB10 synergy
    class CT1,CT2,CT3,CT4,CT5,CT6,CT7 backend
    class UMMAH,MY frontend
    class WPDB db
    class ODY,PI2,OH,CC agent
    class OCL model
    class MBA agent
    class GH,PP,MCP external
    class OCPROXY model

Complete Server Inventory

Node	IP	Role	What runs there
Synology NAS DS3617xs	100.126.73.29 (Tailscale)	Docker Swarm Manager	Traefik, Gitea, Casdoor, PostgreSQL, Redis, Umbrel stack, Halal Monitor, Karakeep, Mattermost, Garage S3, Gitea Runners, Portainer, Dockge, 40+ containers total
Contabo VPS	13.140.161.244 (public)	Swarm Worker + Edge	Traefik edge, Hermes Agent, FalahOS Relay, auto-healer, cron, SSH tunnel
RoketServer cPanel	64.20.37.43	WordPress Host	ummah.falahos.my + my.falahos.my — behind Imunify360
Mac Mini	100.72.2.115 (Tailscale)	Agent Host	Odysseus (:7860), Pi (:4747), OpenHand (:3000), OpenClaw (:3100), Claude Code
MacBook Air	100.76.3.26 (Tailscale)	Agent Host	openclaw MCP (:18789), hermes cron, pi, opencode, agy, claude

Docker Swarm Services (Production)

Service	Stack	Purpose
`falah_traefik`	Swarm	Reverse proxy — routes HTTPS, TLS termination
`gitea_gitea`	Swarm	Git hosting — git.falahos.my (:3080)
`falah_casdoor`	Swarm	Identity provider — auth.falahos.my (:8000)
`falah_falah-mobile`	Swarm	Next.js frontend — falahos.my
`falah_falah-mobile-staging`	Swarm	Staging environment
`falah_postgres`	Swarm	Main application database
`falah_redis`	Swarm	Cache layer
`falah_casdoor-db`	Swarm	Casdoor auth database (Postgres 16)

Standalone Containers (Synology)

Stack	Containers	Purpose
Falah Umbrel	wallet, app, ramz, ummahid, istore, mocknet, carbon, faraid, halal, redis, api-gateway, postgres	Core FalahOS services
Halal Monitor	postgrest, postgis db, nginx gateway	Halal certification monitoring
Karakeep	web, meilisearch, chrome browser	Bookmarking & content keep
Mattermost	app, db	Team chat (internal)
Infrastructure	Portainer, Dockge x2, Watchtower, Garage S3	Docker management + storage
CI/CD	Gitea Runners x3 (act_runner)	Gitea Actions execution
Falah Services	falah-desktop, falah-backend, falah-ui, falah-tunnel, falah-mobile-staging, falah-auto-healer, falah-dns-healer	Supporting services
Other	Linkstack, Affine, iStore, Identity-layer, Auth, Tor proxy, Faraid-anvil (Foundry)	Supporting apps

Key Architecture Facts

Docker Swarm manager lives on Synology NAS, not Contabo — Contabo is a worker node
All production containers run on Synology (via Swarm + standalone)
Gitea runs as a Swarm service on Synology (:3080), fronted by Traefik
Casdoor (auth.falahos.my) replaced the old UmmahID service
Garage S3 provides object storage on Synology
Tailscale connects all nodes in a mesh VPN (100.x.x.x range)
Cloudflare proxies DNS, WAF, and CDN — Traefik handles internal routing
Imunify360 on cPanel blocks datacenter IPs — MacBook Air residential IP used as bypass

📐 Interactive Diagrams

Format	File	Use
🖼️ SVG	FalahOS-Architecture.svg	View inline in browser
📐 Excalidraw	FalahOS-Architecture.excalidraw	Drag onto excalidraw.com to zoom/edit