diff --git a/Home.md b/Home.md index fc4f15b..867a100 100644 --- a/Home.md +++ b/Home.md @@ -20,4 +20,5 @@ See the main repo README for setup instructions. ## Architecture -- **[[Architecture-Diagram]]** — Full FalahOS system architecture diagram (web layer, AI agents, infrastructure, external services) +- **[[Architecture-Diagram]]** — Full FalahOS system architecture (web layer, AI agents, infrastructure, external services) +- **[[TOGAF-Architecture]]** — Complete TOGAF architecture, layer by layer (Business → Data → Application → Technology) diff --git a/TOGAF-Architecture.md b/TOGAF-Architecture.md new file mode 100644 index 0000000..3160104 --- /dev/null +++ b/TOGAF-Architecture.md @@ -0,0 +1,242 @@ +# FalahOS TOGAF Architecture — Layer by Layer + +```mermaid +flowchart TB + %% Styles + classDef business fill:#78350f,stroke:#fbbf24,stroke-width:2 + classDef data fill:#4c1d95,stroke:#a78bfa,stroke-width:2 + 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 + + %% ═══════════════════════════════════════════════ + %% LAYER 1 — 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"] + 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)"] + 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"] + R4["Tutor LMS — Course fees"] + end + end + + %% ═══════════════════════════════════════════════ + %% LAYER 2 — DATA ARCHITECTURE + %% ═══════════════════════════════════════════════ + subgraph DATA["🗄️ L2 — Data Architecture"] + direction TB + + 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 + + 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)"] + CT4["Lead magnet — Islamic Finance Starter Guide"] + 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"] + end + end + + %% ═══════════════════════════════════════════════ + %% LAYER 3 — 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)"] + 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"] + 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"] + 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"] + end + end + + %% ═══════════════════════════════════════════════ + %% LAYER 4 — 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)"] + 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)"] + 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"] + 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"] + end + end + + %% ═══════════════════════════════════════════════ + %% CROSS-LAYER CONNECTIONS + %% ═══════════════════════════════════════════════ + + %% Business → Data + V3 -.->|"drives"| R1 + R1 -.->|"feeds"| F5 + C3 -.->|"produces"| CT1 + + %% Data → Application + D1 -.->|"persists"| A1 + D2 -.->|"hosts"| A4 + D3 -.->|"stores"| AG1 + + %% Application → Technology + A1 -.->|"runs on"| T2 + A2 -.->|"runs on"| T2 + AG1 -.->|"runs on"| T1 + AG2 -.->|"runs on"| T3 + AG6 -.->|"runs on"| T4 + + I3 -.->|"manages"| T2 + I4 -.->|"secures"| N2 + + I1 -.->|"connects via"| N1 +``` + +--- + +## Layer-by-Layer Breakdown + +### 🏢 L1 — Business Architecture +*The business strategy, governance, and revenue model.* + +| 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 | + +### 🗄️ L2 — Data Architecture +*How data is stored, managed, and flows through the system.* + +| 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 | + +### 📱 L3 — Application Architecture +*All applications and their interactions.* + +| 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 | + +### ⚙️ L4 — Technology Architecture +*The hardware, network, and software stack.* + +| 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 | + +| Network | Purpose | +|---------|---------| +| **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) | + +--- + +## 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 |