diff --git a/Architecture-Diagram.md b/Architecture-Diagram.md index 575ccdf..c50abbd 100644 --- a/Architecture-Diagram.md +++ b/Architecture-Diagram.md @@ -2,7 +2,7 @@ ```mermaid flowchart TB - %% Styles - hex colors only (rgba() breaks Mermaid parser) + %% 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 @@ -11,14 +11,15 @@ flowchart TB 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 subg fill:none,stroke:#334155,stroke-width:1,stroke-dasharray:5 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 (ummah + my.falahos.my)"] + WB["Web Browser (falahos.my / ummah / git / auth)"] end %% ── Cloudflare Edge ── @@ -29,121 +30,195 @@ flowchart TB TUN["cloudflared Tunnel"] end - %% ── cPanel Hosting ── - subgraph CP["cPanel Hosting - RoketServer 64.20.37.43"] - UMMAH["ummah.falahos.my WordPress + EDD + MailPoet + Members + Tutor LMS"] - MY["my.falahos.my WordPress + PayPal Standard (Monetisation)"] - MYSQL[("MySQL Shared Database")] - CPT["cPanel Tools (Git / Terminal / Cron / Softaculous)"] - end - - %% ── Contabo VPS ── - subgraph CV["Contabo VPS - 13.140.161.244"] + %% ═══════════════════════════════════════════════════ + %% DOCKER SWARM CLUSTER (Synology Manager + Contabo Worker) + %% ═══════════════════════════════════════════════════ + subgraph SWARM["Docker Swarm Cluster"] direction LR - GW["Hermes Gateway (Telegram / WhatsApp / Systemd)"] - HA["Hermes Agent (Skills / Tools / MCP / Cron)"] - FR["FalahOS Relay (:8088)"] - SHT["SSH Tunnel (-> Mac Mini :17860)"] - end - %% ── External Services ── - subgraph EXT["External Services"] - direction LR - GT["Gitea (git.falahos.my / CI-CD / Wiki)"] - OCP["OpenClaw Proxy (opencode.ai/zen / DeepSeek / Qwen)"] - PP["PayPal Standard (wanjauhari@me.com)"] - MCP["MCP Servers (UI/UX Tester / Browser Tools)"] - end + subgraph SYNOLOGY["Synology NAS DS3617xs (100.126.73.29) — Swarm Manager"] + direction TB - %% ── Agent Fleet ── - subgraph TS["Tailscale Mesh Network"] - subgraph MM["Mac Mini - 100.72.2.115 (macOS 12.7.6)"] - ODY["Odysseus (:7860 - API Gateway)"] - PI["Pi (:4747 - AI Assistant)"] - OH["OpenHand (:3000 - Coding Agent)"] - OCL["OpenClaw (:3100 - Model Provider)"] - CC["Claude Code (CLI - Coding Assistant)"] + 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 - MBA["Hermes MBA (100.76.3.26 - Fallback Agent)"] end - %% ── Connections ── - TG --> GW - WA --> GW + %% ═══════════════════════════════════════════════════ + %% 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 - GW --> HA - HA --> FR - HA --> SHT - FR --> ODY - FR --> PI - FR --> OH - FR --> OCL - FR --> CC - FR --> MBA - SHT -.->|Port Forward| ODY - UMMAH --> MYSQL - MY --> MYSQL - UMMAH --> CPT - MY -.->|Payment IPN| PP - UMMAH -.->|Git Deploy| GT - HA -.->|CI-CD| GT - OCL -.->|API Calls| OCP + + %% 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 GW,HA,FR,SHT backend - class MYSQL db - class ODY,PI,OH,CC agent - class MBA backend - class GT,PP,MCP external - class OCL,OCP model + class WPDB db + class ODY,PI2,OH,CC agent + class OCL model + class MBA agent + class GH,PP,MCP external + class OCPROXY model ``` --- -## System Overview +## Complete Server Inventory -### Web Layer -| Component | Details | -|-----------|---------| -| **ummah.falahos.my** | Primary WordPress — EDD (payments), MailPoet (email), Members (access), Tutor LMS (courses) | -| **my.falahos.my** | Monetisation subdomain — PayPal Standard checkout | -| **Cloudflare** | DNS proxied, WAF rules, cloudflared tunnel | -| **cPanel (RoketServer)** | Shared hosting at 64.20.37.43 — Imunify360 blocks datacenter IPs | +| 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 | -### AI Agent Layer -| Component | Host | Role | -|-----------|------|------| -| **Hermes Agent** | Contabo VPS 13.140.161.244 | Primary orchestrator — skills, tools, MCP, cron | -| **Hermes Gateway** | Contabo VPS | Telegram + WhatsApp messaging (systemd) | -| **FalahOS Relay** | Contabo VPS :8088 | Telegram relay bus to agent fleet | +## Docker Swarm Services (Production) -### Agent Fleet (Tailscale Mesh) -| Agent | Host | Port | Purpose | -|-------|------|------|---------| -| **Odysseus** | Mac Mini 100.72.2.115 | :7860 | API Gateway, AI chat, email, documents | -| **Pi** | Mac Mini 100.72.2.115 | :4747 | AI assistant agent | -| **OpenHand** | Mac Mini 100.72.2.115 | :3000 | Autonomous coding agent | -| **OpenClaw** | Mac Mini 100.72.2.115 | :3100 | Model provider proxy (DeepSeek, Qwen) | -| **Claude Code** | Mac Mini 100.72.2.115 | CLI | Coding assistant | -| **Hermes (MBA)** | MacBook Air 100.76.3.26 | — | Fallback agent, residential IP | +| 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) | -### External Integrations -| Service | URL | Purpose | -|---------|-----|---------| -| **Gitea** | git.falahos.my | Git repos, CI/CD Actions, Wiki | -| **OpenClaw Proxy** | opencode.ai/zen | Model inference (DeepSeek v4 Flash/Pro, Qwen 3.6) | -| **PayPal Standard** | wanjauhari@me.com | Payment processing | +## Standalone Containers (Synology) -### Key Architecture Decisions -- **Hybrid model**: cPanel hosts web frontend/payments/email — Mac Mini/Contabo handle AI compute -- **Tailscale mesh** for inter-agent routing (no exposed ports, direct connections) -- **FalahOS Ops Chat** as unified agent coordination channel -- **Imunify360** blocks datacenter IPs — cPanel Git/Terminal APIs used as bypass -- **Residential IP** (MacBook Air) provides bypass for Imunify360 JS challenges +| 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 diff --git a/TOGAF-Architecture.md b/TOGAF-Architecture.md index 3160104..d55f89b 100644 --- a/TOGAF-Architecture.md +++ b/TOGAF-Architecture.md @@ -8,170 +8,215 @@ flowchart TB classDef app fill:#083344,stroke:#22d3ee,stroke-width:2 classDef tech fill:#064e3b,stroke:#34d399,stroke-width:2 classDef ext fill:#1e293b,stroke:#94a3b8,stroke-width:1.5 + classDef product fill:#881337,stroke:#fb7185,stroke-width:1.5 - %% ═══════════════════════════════════════════════ - %% LAYER 1 — BUSINESS ARCHITECTURE - %% ═══════════════════════════════════════════════ - subgraph BIZ["🏢 L1 — Business Architecture"] + %% ═══════════════════════════════════════════════════ + %% L1 — BUSINESS ARCHITECTURE + %% ═══════════════════════════════════════════════════ + subgraph BIZ["L1 — Business Architecture"] direction TB - subgraph VISION["Vision & Strategy"] - V1["Vision: Islamic Fintech OS for the Ummah"] - V2["Mission: Democratise Islamic finance education & tools"] - V3["Revenue Model: Digital products + memberships + payments"] + VISION["Vision: Shariah-compliant digital economy platform (Falah OS v1.3)"] + MISSION["Mission: Democratise Islamic finance, halal certification, inheritance planning"] + + subgraph PRODUCTS["Products & Modules"] + P1["Faraid Tokenisation — Islamic inheritance automation (Solidity + Foundry)"] + P2["Halal Certification — ASEAN halal monitoring & certification"] + P3["Falah Mobile — Islamic lifestyle app (Next.js)"] + P4["Islamic Finance Education — Courses, newsletter, content"] + P5["FLH Token Wallet — Falah utility token (in development)"] + P6["Falah Souq — Halal marketplace (in development)"] end - subgraph CHANNELS["Go-to-Market Channels"] - C1["Telegram — @FalahOS_opsbot DM + group chat"] - C2["WhatsApp — +6013-225 0691 Baileys bridge"] - C3["Web — ummah.falahos.my (education / content)"] - C4["Web — my.falahos.my (monetisation / products)"] + subgraph CHANNELS["Channels"] + C1["ummah.falahos.my — Community portal (WordPress)"] + C2["my.falahos.my — Monetisation subdomain"] + C3["falahos.my — Mobile app frontend (Next.js)"] + C4["Telegram — @FalahOS_opsbot (DM + Ops Chat)"] + C5["WhatsApp — +6013-225 0691 (Baileys bridge)"] + C6["git.falahos.my — Gitea (source control + wiki)"] + C7["GitHub (maifors) — Public mirror + faraid-sandbox"] end - subgraph STAKEHOLDERS["Stakeholders"] - S1["Founder: WMJ Ismail (Product / Strategy)"] - S2["Audience: Muslim professionals seeking Islamic finance knowledge"] - S3["Students: Tutor LMS course enrollees"] - S4["Subscribers: MailPoet email newsletter"] - end - - subgraph REVENUE["Revenue Streams"] - R1["PayPal Standard — wanjauhari@me.com"] - R2["EDD — Digital product sales (RM0–RM299)"] - R3["Members — Paid membership tiers"] + subgraph REVENUE["Revenue"] + R1["EDD — Digital product sales (RM0–RM299)"] + R2["PayPal Standard (wanjauhari@me.com)"] + R3["MemberPress — Paid memberships"] R4["Tutor LMS — Course fees"] + R5["MailPoet — Newsletter subscribers"] end end - %% ═══════════════════════════════════════════════ - %% LAYER 2 — DATA ARCHITECTURE - %% ═══════════════════════════════════════════════ - subgraph DATA["🗄️ L2 — Data Architecture"] - direction TB + %% ═══════════════════════════════════════════════════ + %% L2 — DATA ARCHITECTURE + %% ═══════════════════════════════════════════════════ + subgraph DATA["L2 — Data Architecture"] - subgraph STORAGE["Data Stores"] - D1["MySQL — WordPress DB (posts, users, orders, courses, members)"] - D2["Gitea — Git repos + Wiki + CI/CD artifacts"] - D3["Hermes — Session store + Memory + Cron state"] - D4["Mac Mini — Agent configs + state + logs"] - end + DB1[("PostgreSQL 16 (Swarm) — Main app database\nfalah-mobile, Casdoor, services")] + DB2[("PostgreSQL (Synology) — Casdoor DB, Mattermost DB\nHalal Monitor PostGIS, Umbrel stack DBs")] + DB3[("MySQL (cPanel) — WordPress DB\nposts, users, orders, members, courses")] + DB4[("Redis 7 (Swarm + Synology) — Cache layer\nsessions, queues, real-time")] + DB5[("Garage S3 (Synology) — Object storage\nfiles, backups, assets")] + DB6[("Memcached (Synology) — Distributed cache")] + DB7[("Meilisearch (Synology) — Full-text search (Karakeep)")] subgraph CONTENT["Content Library"] - CT1["AI-generated blog posts (12 SEO-optimised articles)"] - CT2["EDD product descriptions (7 digital products)"] - CT3["MailPoet email sequences (10 automated emails)"] + CT1["AI-generated blog posts (12 SEO)"] + CT2["EDD products (7 descriptions)"] + CT3["MailPoet sequences (10 emails)"] CT4["Lead magnet — Islamic Finance Starter Guide"] + CT5["Faraid whitepapers (ASSJ, v2, 8-paper synthesis)"] + CT6["Newsletter editions (Falah Letter)"] end - subgraph FLOW["Data Flows"] - F1["WordPress ← Content pipeline (AI-generated → WP REST API)"] - F2["Gitea ← Git push CI/CD triggers → Deploy WordPress"] - F3["Hermes ← Telegram/WhatsApp messages → Agent processing"] - F4["Agents ← Relay bus → Hermes orchestrator ← External APIs"] - F5["PayPal IPN ← EDD ← Customer checkout"] + subgraph CODE["Code & Config"] + GC1["Gitea repos: falah-os-master, falah-mobile, war-room, cpanel-db-backups, falahmobile-content, hermes-cpanel-agent"] + GC2["GitHub repos: faraid-sandbox, falah-umbrel, falah-extension, falah-os-sdk, falah-mobile-staging"] + GC3["Agent states: Hermes memory + sessions, OpenClaw config, Odysseus state"] + GC4["Stack files: /opt/falah-os/swarm/ (falah-stack.yml, gitea-stack.yml)"] end end - %% ═══════════════════════════════════════════════ - %% LAYER 3 — APPLICATION ARCHITECTURE - %% ═══════════════════════════════════════════════ - subgraph APP["📱 L3 — Application Architecture"] + %% ═══════════════════════════════════════════════════ + %% L3 — APPLICATION ARCHITECTURE + %% ═══════════════════════════════════════════════════ + subgraph APP["L3 — Application Architecture"] direction TB - subgraph WEB["Web Applications"] - A1["WordPress — ummah.falahos.my (primary site)"] - A2["WordPress — my.falahos.my (monetisation subdomain)"] - A3["Odysseus — ody.falahos.my (API gateway / AI chat / email / documents)"] - A4["Gitea — git.falahos.my (source control / CI-CD / wiki)"] + subgraph SWARM_SERVICES["Docker Swarm Services (Synology Mgr + Contabo Worker)"] + S1["Traefik v2 — Reverse proxy, TLS termination"] + S2["Gitea 1.26 — git.falahos.my (:3080)"] + S3["Casdoor — auth.falahos.my (Identity Provider)"] + S4["falah-mobile — Next.js (falahos.my)"] + S5["falah-mobile-staging — Staging environment"] + S6["PostgreSQL 16 — Main app DB"] + S7["Redis 7 — Cache layer"] end - subgraph PLUGINS["WordPress Plugins"] - P1["Easy Digital Downloads (EDD) — Digital product sales"] - P2["MailPoet — Email newsletters + automations"] - P3["MemberPress — Paid membership access control"] - P4["Tutor LMS — Online course platform"] - P5["Code Snippets — Custom PHP/JS snippets"] + subgraph SYNO_STANDALONE["Synology Standalone Containers"] + SY1["Falah Umbrel: wallet, app, ramz, ummahid, istore, mocknet, carbon, faraid, halal, redis, api-gateway, postgres"] + SY2["Halal Monitor: postgrest + postgis gateway"] + SY3["Karakeep: bookmarking + meilisearch + chrome"] + SY4["Mattermost: team chat + db"] + SY5["Gitea Runners x3: CI/CD execution"] + SY6["Falah services: desktop, backend, UI, tunnel, auto-healer, dns-healer"] + SY7["Garage S3: Object storage"] + SY8["Portainer / Dockge x2 / Watchtower / Linkstack / Affine / iStore / Identity-layer"] + SY9["Faraid-anvil: Foundry (blockchain dev)"] + end + + subgraph CPANEL_WP["cPanel / WordPress"] + WP1["WordPress — ummah.falahos.my"] + WP2["WordPress — my.falahos.my"] + WPP["Plugins: EDD, MailPoet, bbPress, GamiPress, Tutor LMS\nfalah-wallet, falah-souq, nur-ai-coach, islamic-tools"] end subgraph AGENTS["AI Agents"] - AG1["Hermes Agent (Contabo) — Primary orchestrator / tools / skills / MCP"] - AG2["Odysseus (Mac Mini) — API gateway, AI chat, email, calendar, research"] - AG3["Pi (Mac Mini) — AI assistant for delegated tasks"] - AG4["OpenHand (Mac Mini) — Autonomous coding agent"] - AG5["Claude Code (Mac Mini) — CLI coding assistant"] - AG6["Hermes MBA (MacBook Air) — Fallback agent via residential IP"] + A1["Hermes Agent (Contabo) — Orchestrator / skills / tools / MCP / cron"] + A2["Odysseus (Mac Mini :7860) — API gateway, AI chat, email, docs, research"] + A3["Pi (Mac Mini :4747) — AI assistant"] + A4["OpenHand (Mac Mini :3000) — Autonomous coding agent"] + A5["OpenClaw (Mac Mini :3100) — Model provider proxy"] + A6["Claude Code (Mac Mini CLI) — Coding assistant"] + A7["openclaw (MBA :18789) — MCP gateway, WhatsApp routing"] + A8["Hermes MBA — Fallback agent + cron scheduler"] end - subgraph INFRA_APPS["Infrastructure Applications"] - I1["FalahOS Relay — Telegram message bus (Contabo :8088)"] - I2["OpenClaw — Model provider proxy (Mac Mini :3100)"] - I3["cPanel — Hosting dashboard (Git / Terminal / Cron / Softaculous)"] - I4["Cloudflare — DNS / WAF / CDN / Tunnel"] - I5["MCP Servers — UI/UX Tester, Browser tools"] + subgraph INFRA_APPS["Infrastructure"] + I1["FalahOS Relay (Contabo :8088) — Telegram message bus"] + I2["Cloudflare — DNS / WAF / CDN / tunnel"] + I3["Traefik — Internal routing + TLS"] + I4["falah-auto-healer — Hourly health recovery"] + I5["falah-dns-healer — DNS recovery script"] + I6["Komodo — GitOps deployment manager"] + I7["MCP Servers — UI/UX Tester, Browser tools"] end end - %% ═══════════════════════════════════════════════ - %% LAYER 4 — TECHNOLOGY ARCHITECTURE - %% ═══════════════════════════════════════════════ - subgraph TECH["⚙️ L4 — Technology Architecture"] + %% ═══════════════════════════════════════════════════ + %% L4 — TECHNOLOGY ARCHITECTURE + %% ═══════════════════════════════════════════════════ + subgraph TECH["L4 — Technology Architecture"] direction TB - subgraph COMPUTE["Compute / Hosting"] - T1["Contabo VPS — 13.140.161.244 (6 vCPU / 16GB / 400GB SSD)"] - T2["RoketServer cPanel — 64.20.37.43 (Shared hosting / Imunify360)"] - T3["Mac Mini — 100.72.2.115 (macOS 12.7.6 / 8GB / Tailscale)"] - T4["MacBook Air — 100.76.3.26 (macOS / Residential IP / Tailscale)"] + subGRAPH NODES["Physical / Virtual Nodes"] + N1["Synology DS3617xs — DSM 6.2.3\n8GB RAM, 4x volumes (890G+443G+855G)\nTailscale 100.126.73.29"] + N2["Contabo VPS — Ubuntu 24.04\n6 vCPU / 16GB / 400GB SSD\nPublic: 13.140.161.244"] + N3["RoketServer cPanel — Shared hosting\n64.20.37.43, Imunify360"] + N4["Mac Mini — macOS 12.7.6\n8GB RAM\nTailscale 100.72.2.115"] + N5["MacBook Air — macOS\nTailscale 100.76.3.26"] end - subgraph NETWORK["Network / Connectivity"] - N1["Tailscale — Mesh VPN (direct connections between all nodes)"] - N2["Cloudflare — Proxied DNS / WAF / CDN / cloudflared tunnel"] - N3["Imunify360 — cPanel security (blocks datacenter IPs)"] - N4["SSH Tunnel — Contabo :17860 → Mac Mini :7860 (ComfyUI)"] + subgraph NETWORK["Network"] + NW1["Tailscale Mesh VPN — 100.x.x.x range (all nodes)"] + NW2["Cloudflare — DNS proxy + WAF + CDN"] + NW3["Docker Swarm Overlay — Synology ↔ Contabo"] + NW4["SSH Tunnel — Contabo :17860 ↔ Mac Mini :7860"] + NW5["Imunify360 — cPanel security (blocks datacenter IPs)"] + NW6["Traefik v2 — Internal service routing"] end - subgraph STACK["Software Stack"] - SFT1["OS: Ubuntu 24.04 (Contabo) / macOS 12.7.6 (Mac Mini)"] - SFT2["Runtime: Python 3.11 / Node.js 22 / PHP 8.x / Nginx"] - SFT3["Database: MySQL 8.x (cPanel shared)"] - SFT4["Container: Docker (Contabo) / Docker Swarm (planned)"] - SFT5["Agent: Hermes CLI + Gateway / OpenClaw / OpenHand CLI"] + subgraph RUNTIME["Runtime / Software Stack"] + RT1["Docker (Synology) — Swarm manager + standalone containers"] + RT2["Docker (Contabo) — Swarm worker node"] + RT3["Python 3.11 / Node.js 22 / PHP 8.x / Nginx"] + RT4["PostgreSQL 16 / MySQL 8 / Redis 7"] + RT5["Solidity + Foundry (Faraid blockchain)"] + RT6["Hermes CLI + Gateway / OpenClaw / OpenHand CLI"] end - subgraph SECURITY["Security"] - SEC1["Cloudflare WAF — OWASP rules + rate limiting"] - SEC2["Imunify360 — cPanel account protection + mod_security"] - SEC3["Tailscale ACLs — Inter-agent access policies"] - SEC4["PayPal IPN — Payment notification verification"] + subgraph CI_CD["CI / CD Pipeline"] + CI1["Gitea Actions — 3x act_runner (Synology)"] + CI2["Komodo — GitOps stack deploys (webhook → Docker Swarm)"] + CI3["cPanel Git — WordPress deployment via Git API"] + CI4["Auto-healer — Hourly health recovery cron"] + CI5["Daily agent crons — Wiki sync, board sync, health checks"] end end - %% ═══════════════════════════════════════════════ + %% ═══════════════════════════════════════════════════ %% CROSS-LAYER CONNECTIONS - %% ═══════════════════════════════════════════════ + %% ═══════════════════════════════════════════════════ %% Business → Data - V3 -.->|"drives"| R1 - R1 -.->|"feeds"| F5 - C3 -.->|"produces"| CT1 + P1 -.->|"data in"| GC1 + R1 -.->|"feeds"| DB3 + C4 -.->|"messages"| A1 %% Data → Application - D1 -.->|"persists"| A1 - D2 -.->|"hosts"| A4 - D3 -.->|"stores"| AG1 + DB1 -.->|"persists"| S4 + DB3 -.->|"persists"| WP1 + GC2 -.->|"CI/CD"| CI1 %% Application → Technology - A1 -.->|"runs on"| T2 - A2 -.->|"runs on"| T2 - AG1 -.->|"runs on"| T1 - AG2 -.->|"runs on"| T3 - AG6 -.->|"runs on"| T4 + S1 -.->|"runs on"| N1 + S2 -.->|"runs on"| N1 + A1 -.->|"runs on"| N2 + A2 -.->|"runs on"| N4 + A7 -.->|"runs on"| N5 + WP1 -.->|"runs on"| N3 - I3 -.->|"manages"| T2 - I4 -.->|"secures"| N2 + CI1 -.->|"executes on"| N1 + NW1 -.->|"connects"| N2 + NW1 -.->|"connects"| N4 + NW1 -.->|"connects"| N5 + NW1 -.->|"connects"| N1 - I1 -.->|"connects via"| N1 + %% Assign classes + class P1,P2,P3,P4,P5,P6 product + class R1,R2,R3,R4,R5 business + class C1,C2,C3,C4,C5,C6,C7 business + class DB1,DB2,DB3,DB4,DB5,DB6,DB7 data + class S1,S2,S3,S4,S5,S6,S7 app + class SY1,SY2,SY3,SY4,SY5,SY6,SY7,SY8,SY9 app + class WP1,WP2,WPP app + class A1,A2,A3,A4,A5,A6,A7,A8 app + class I1,I2,I3,I4,I5,I6,I7 app + class N1,N2,N3,N4,N5 tech + class NW1,NW2,NW3,NW4,NW5,NW6 tech + class RT1,RT2,RT3,RT4,RT5,RT6 tech + class CI1,CI2,CI3,CI4,CI5 tech + class VISION,MISSION business ``` --- @@ -179,64 +224,75 @@ flowchart TB ## Layer-by-Layer Breakdown ### 🏢 L1 — Business Architecture -*The business strategy, governance, and revenue model.* +*Strategy, governance, products, and revenue.* -| Element | Details | -|---------|---------| -| **Vision** | Islamic Fintech OS for the global Muslim community (Ummah) | -| **Mission** | Democratise Islamic finance education, tools, and digital products | -| **Revenue Model** | Digital products (EDD) + Paid memberships (MemberPress) + Course fees (Tutor LMS) | -| **Founder** | WMJ Ismail — product owner, strategy, content direction | -| **Audience** | Muslim professionals seeking Islamic finance knowledge | -| **Channels** | Telegram (primary), WhatsApp (secondary), Web (content + sales) | -| **Payments** | PayPal Standard (`wanjauhari@me.com`) — RM0 to RM299 pricing | +| Area | Details | +|------|---------| +| **Vision** | Shariah-compliant digital economy platform (Falah OS v1.3) | +| **Products** | Faraid Tokenisation, Halal Certification, Falah Mobile, Islamic finance education, FLH Wallet, Falah Souq | +| **Channels** | ummah.falahos.my (WordPress), falahos.my (Next.js), Telegram, WhatsApp, Gitea, GitHub | +| **Revenue** | EDD digital products + PayPal Standard + MemberPress + Tutor LMS courses + MailPoet newsletter | +| **Audience** | Muslim professionals seeking Islamic finance, halal, inheritance solutions | ### 🗄️ L2 — Data Architecture -*How data is stored, managed, and flows through the system.* +*How data is stored, managed, and flows.* -| Element | Details | -|---------|---------| -| **Primary DB** | MySQL 8.x — WordPress (posts, users, orders, members, courses) | -| **Source Control** | Gitea — Git repos, wiki documentation, CI/CD pipeline | -| **Agent State** | Hermes session store + persistent memory + cron job definitions | -| **Content Library** | 12 SEO blog posts, 7 EDD products, 10 MailPoet emails, lead magnet | -| **Key Data Flows** | Content pipeline → WP REST API; PayPal IPN → EDD; Relay bus → Agents | +| Data Store | Type | Host | Purpose | +|-----------|------|------|---------| +| PostgreSQL 16 | Relational | Swarm (Synology) | App DB, Casdoor, Mattermost, Umbrel stack | +| PostgreSQL 16 | Relational | Swarm (Synology) | Casdoor auth DB, Halal Monitor PostGIS | +| MySQL 8 | Relational | cPanel (RoketServer) | WordPress (posts, users, orders, courses) | +| Redis 7 | Cache | Swarm + Synology | Session cache, queues, real-time | +| Garage S3 | Object | Synology | File storage, backups, assets | +| Meilisearch | Search | Synology | Full-text (Karakeep) | +| Gitea | Git | Swarm (Synology) | Source code, wiki, CI/CD artifacts | +| GitHub | Git | External | Public mirror, faraid-sandbox | ### 📱 L3 — Application Architecture -*All applications and their interactions.* +*All applications, agents, and services.* -| Category | Applications | -|----------|-------------| -| **Web Apps** | WordPress (ummah.falahos.my + my.falahos.my), Odysseus API gateway, Gitea | -| **WP Plugins** | EDD, MailPoet 4, MemberPress, Tutor LMS, Code Snippets | -| **AI Agents** | Hermes (orchestrator), Odysseus (gateway), Pi, OpenHand, Claude Code, Hermes MBA | -| **Infrastructure** | FalahOS Relay, OpenClaw proxy, cPanel, Cloudflare, MCP servers | +| Category | Components | Location | +|----------|-----------|----------| +| **Swarm Services** | Traefik, Gitea, Casdoor, falah-mobile, staging, PostgreSQL, Redis | Synology (mgr) + Contabo (worker) | +| **Synology Standalone** | Umbrel stack (9 containers), Halal Monitor (3), Karakeep (3), Mattermost (2), Gitea Runners (3), Garage S3, Portainer, Dockge (2), Watchtower, Falah services (7), Linkstack, Affine, iStore, Identity-layer, Auth, Faraid-anvil | Synology NAS | +| **WordPress** | ummah.falahos.my + my.falahos.my — EDD, MailPoet, bbPress, GamiPress, Tutor LMS, falah-wallet, falah-souq, nur-ai-coach, islamic-tools | cPanel (RoketServer) | +| **AI Agents** | Hermes (Contabo), Odysseus (Mac Mini :7860), Pi (:4747), OpenHand (:3000), OpenClaw (:3100), Claude Code, openclaw MCP (MBA :18789) | Contabo / Mac Mini / MBA | +| **Infrastructure** | FalahOS Relay, Cloudflare, Traefik, auto-healer, dns-healer, Komodo, MCP servers | Various | ### ⚙️ L4 — Technology Architecture -*The hardware, network, and software stack.* +*Hardware, network, runtime, and CI/CD.* | Node | Spec | Role | |------|------|------| -| **Contabo VPS** | 6 vCPU / 16GB RAM / 400GB SSD / Ubuntu 24.04 | Hermes Agent, Relay, Cron | -| **RoketServer cPanel** | Shared hosting / Imunify360 / 64.20.37.43 | WordPress, MySQL, Email | -| **Mac Mini** | macOS 12.7.6 / 8GB RAM / 100.72.2.115 | Agent fleet (Ody, Pi, OpenHand, OpenClaw, Claude) | -| **MacBook Air** | macOS / Residential IP / 100.76.3.26 | Fallback Hermes instance | +| **Synology DS3617xs** | DSM 6.2.3, 8GB RAM, 4 volumes (2.6TB total), Tailscale 100.126.73.29 | **Swarm Manager** — runs ALL production containers | +| **Contabo VPS** | Ubuntu 24.04, 6 vCPU / 16GB / 400GB SSD, 13.140.161.244 | **Swarm Worker** + Edge node / Hermes | +| **RoketServer cPanel** | Shared hosting, Imunify360, 64.20.37.43 | **WordPress** host | +| **Mac Mini** | macOS 12.7.6, 8GB RAM, 100.72.2.115 | Agent host (Odysseus, Pi, OpenHand, OpenClaw, Claude) | +| **MacBook Air** | macOS, 100.76.3.26 | Agent host (openclaw MCP, hermes cron, pi, opencode) | -| Network | Purpose | +| Network | Details | |---------|---------| -| **Tailscale** | Mesh VPN — direct encrypted connections between all nodes | -| **Cloudflare** | DNS proxying, WAF, CDN caching, cloudflared tunnel | -| **SSH Tunnel** | Contabo :17860 → Mac Mini :7860 (ComfyUI port forward) | +| **Tailscale Mesh** | All nodes connected via mesh VPN (100.x.x.x range) | +| **Docker Swarm Overlay** | Synology (manager) ↔ Contabo (worker) | +| **Cloudflare** | DNS proxied, WAF, CDN, cloudflared tunnels | +| **SSH Tunnel** | Contabo :17860 → Mac Mini :7860 (ComfyUI) | ---- +| CI/CD | Details | +|-------|---------| +| **Gitea Actions** | 3x act_runner on Synology — runs CI/CD pipelines | +| **Komodo** | GitOps deployment manager (webhook → Docker Swarm deploy) | +| **cPanel Git** | WordPress deployment via Git API | +| **Auto-healer** | Hourly health check + auto-recovery on Contabo | +| **Agent crons** | Daily 9am: wiki compile, board sync, comprehensive health checks | ## Architecture Principles | # | Principle | Rationale | |---|-----------|-----------| -| 1 | **Hybrid hosting** | cPanel for web frontend/payments/email; VPS + Mac Mini for AI compute — best of both worlds | -| 2 | **Tailscale first** | No exposed ports — all agent communication via encrypted mesh VPN | -| 3 | **API-driven content** | AI generates content → WP REST API deploys → no manual steps | -| 4 | **Defence in depth** | Cloudflare WAF → Imunify360 → Tailscale ACLs — triple security layer | -| 5 | **Residential bypass** | MacBook Air provides residential IP to bypass Imunify360 datacenter blocking | -| 6 | **Progressive monetisation** | Free content → Lead magnet → Paid products → Memberships → Courses | +| 1 | **Synology is core** | Docker Swarm manager + 40+ containers — single point of infrastructure | +| 2 | **Hybrid orchestration** | Swarm for production services, standalone for specialised containers | +| 3 | **Tailscale mesh** | Zero exposed ports — all inter-node traffic via encrypted mesh VPN | +| 4 | **Agent-driven ops** | AI agents handle CI/CD, health monitoring, content, wiki sync autonomously | +| 5 | **Defence in depth** | Cloudflare WAF → Imunify360 → Traefik → Tailscale ACLs | +| 6 | **Multi-agent fleet** | 8+ specialised agents (Hermes, Odysseus, Pi, OpenHand, OpenClaw, Claude) each with defined role | +| 7 | **Progressive monetisation** | Free content → Lead magnet → Digital products → Memberships → Courses |