diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e054ac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# Falah OS — Community Edition
+
+Islamic finance operating system with integrated Zakat, Waqf, Qurban, Sadaqah, and Infaq modules.
+
+## Architecture
+
+```
+falah-app (React + Vite + Tailwind) — port 3005
+├── Zakat Vault     → falah-zakat  (port 3011)
+├── Waqf Chain      → falah-waqf   (port 3012)
+├── Qurban          → falah-qurban (port 3016)
+├── Sadaqah Stream  → falah-sadaqah(port 3014)
+├── Infaq           → falah-infaq  (port 3015)
+├── Wallet          → wallet       (port 3002)
+├── Ummah ID        → ummahid      (port 3001)
+├── RAMZ            → ramz         (port 3003)
+├── Prayer          → prayer       (port 3008)
+├── Chat            → chat         (port 3009)
+├── Community       → community    (port 3007)
+├── Mock-Net        → mocknet      (port 3004)
+├── Halal Certs     → certs        (port N/A)
+└── API Gateway     → gateway      (port 3000)
+```
+
+All microservices use Express with in-memory Maps (v1.3 pattern — no PostgreSQL dependency).
+
+## Stack
+
+- **Frontend**: TypeScript, React, Vite, Tailwind CSS
+- **Backend**: Express.js, in-memory storage
+- **Deploy**: Docker, docker-compose on Synology NAS (Alpine Linux)
+
+## Quick Start
+
+```bash
+npm install
+npm run dev        # Vite dev server (hot reload)
+npm run build      # Production build → dist/
+node server.cjs    # Serve dist/ on port 3000
+```
+
+## Docker
+
+```bash
+docker build -t falah-app .
+docker run -d -p 3005:3000 falah-app
+```
+
+## Modules
+
+| Module | Port | Description |
+|--------|------|-------------|
+| Zakat Vault | 3011 | Nisab calculation, asset/liability wizard, history |
+| Waqf Chain | 3012 | Endowment project listing, donations, certificates |
+| Qurban | 3016 | Eid sacrifice booking (goat/sheep/cow/camel) |
+| Sadaqah Stream | 3014 | Recurring micro-charity with cause explorer |
+| Infaq | 3015 | Community crowdfunding campaigns |
+
+## UI Features
+
+- Draggable app windows with macOS-style window manager
+- Dock with auto-hide toggle
+- Right-click context menu (wallpaper, iStore, system info)
+- Clock/date display, balance/contracts/certs widgets
+- App search bar with `/` keyboard shortcut
+
+## License
+
+Falah Consultancy Limited