wmj/falah-mobile
1
0
Fork 0
Code Issues 3 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix: complete architecture rewrite — add Synology NAS (Swarm manager), Docker Swarm cluster, 40+ containers, full server inventory, GitHub repos, Faraid, Halal Monitor, all missing services

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