From b6103cbb0167031e49c41d81de164b6a151256ec Mon Sep 17 00:00:00 2001
From: root <root@dev-erp-next.lan>
Date: Thu, 16 Jul 2026 09:23:22 +0000
Subject: [PATCH] chore: add human-readable deployment docs to README.md

---
 AGENTS.md |   2 +-
 README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 104 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e8d252b..1b79190 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # Service Factory — ERPNext Custom App Project
 
-> **Current Version: V0.1.0009** — Each completed prompt/step increments the patch number by 1 (V0.1.0000 → V0.1.0001 → V0.1.0002…). The agent automatically commits and pushes after every step.
+> **Current Version: V0.1.0010** — Each completed prompt/step increments the patch number by 1 (V0.1.0000 → V0.1.0001 → V0.1.0002…). The agent automatically commits and pushes after every step.
 
 ## Project Overview
 
diff --git a/README.md b/README.md
index 806565e..9714009 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,65 @@
-### Service Factory
+# Service Factory
 
-Professional Services Delivery & Capacity Management
+Professional Services Delivery & Capacity Management — a custom Frappe/ERPNext app.
 
-### Installation
+## Deployment Architecture
 
-You can install this app using the [bench](https://github.com/frappe/bench) CLI:
+### Production Stack
+
+```
+                         ┌──────────────────────┐
+                         │     Zoraxy Proxy      │
+                         │  (SSL termination)    │
+                         │  Port 443 → 8000      │
+                         │  /socket.io → :9000   │
+                         │  WebSocket passthrough │
+                         └──────┬───────────────┘
+                                │
+                    ┌───────────┴───────────┐
+                    │    Nginx (8000+8080)   │
+                    │                       │
+                    │  /assets/ → filesystem │
+                    │  /socket.io → :9000    │
+                    │  /* → gunicorn :8001   │
+                    └───────┬──────────┬────┘
+                            │          │
+                    ┌───────┴──┐  ┌────┴────────┐
+                    │ Gunicorn │  │ Socket.IO   │
+                    │ :8001    │  │ Node.js :9000│
+                    └──────────┘  └─────────────┘
+```
+
+### Key Configuration
+
+| Component | Setting | Notes |
+|-----------|---------|-------|
+| **Zoraxy** | WebSocket passthrough: **enabled** | Required for real-time updates |
+| **Zoraxy** | Virtual directory: `/socket.io` → `http://172.16.8.20:9000/socket.io` | Routes WebSocket directly to socket.io server |
+| **Nginx** | `/assets/` served directly from filesystem | Bypasses gunicorn — essential for correct CSS/JS MIME types behind proxies |
+| **Nginx** | `proxy_set_header Host erp.lohmar.co.uk` | Set for socket.io location to pass origin checks |
+| **Socket.io** | Origin check **disabled** in `authenticate.js` | Socket.io's built-in CORS handles security; middleware check breaks behind proxies |
+
+### Services
+
+| Service | Port | Description |
+|---------|------|-------------|
+| `frappe-bench-web.service` | 8001 | Gunicorn (Frappe web app) — behind nginx |
+| `frappe-bench-worker.service` | — | Background async worker |
+| `frappe-bench-schedule.service` | — | Scheduled job runner |
+| `frappe-bench-socketio.service` | 9000 | Realtime WebSocket (Node.js) |
+| `frappe-bench-watch.service` | — | File watcher for dev/assets |
+
+### Ports
+
+| Port | Purpose |
+|------|---------|
+| 443 | Zoraxy HTTPS → nginx :8000 |
+| 8080 | Nginx direct (no SSL, for testing) |
+| 8000 | Nginx (Zoraxy target) |
+| 8001 | Gunicorn (behind nginx) |
+| 9000 | Socket.io Node.js server |
+
+## Installation
 
 ```bash
 cd $PATH_TO_YOUR_BENCH
@@ -12,22 +67,57 @@ bench get-app $URL_OF_THIS_REPO --branch version-16
 bench install-app service_factory
 ```
 
-### Contributing
+### Post-Install
 
-This app uses `pre-commit` for code formatting and linting. Please [install pre-commit](https://pre-commit.com/#installation) and enable it for this repository:
+1. Create Zoraxy virtual directory: `/socket.io` → `http://[server-ip]:9000/socket.io` with WebSocket passthrough enabled
+2. Configure nginx to serve `/assets/` directly (see nginx config in `deploy/`)
+3. If behind a reverse proxy, disable the socket.io origin check in `frappe/realtime/middlewares/authenticate.js`
+
+## DocTypes
+
+### Engagement Card (the core)
+
+The primary work tracking DocType with:
+- **Assignments** — Multi-person team allocation
+- **Activity Log** — Timestamped comments, milestones, notes
+- **Time Log** — Per-employee hours tracking
+- **Subtasks** — Delegatable breakdown items
+
+Card types: SE (Sales Engineering), PS (Professional Services), MS (Managed Services), Support
+
+### Status Flow
+```
+Discovery → Delivery → Complete → Archived
+```
+
+## Development
+
+### Prerequisites
+- Python ≥3.14
+- Node.js/Bun
+- pre-commit
+
+### Setup
 
 ```bash
 cd apps/service_factory
 pre-commit install
 ```
 
-Pre-commit is configured to use the following tools for checking and formatting your code:
+Pre-commit runs ruff, eslint, prettier, and pyupgrade on commit.
 
-- ruff
-- eslint
-- prettier
-- pyupgrade
+### Agent Workflow
 
-### License
+This project uses OpenAgentsControl. The agent operates in two modes:
+- **🗣️ Discuss** — Architecture, design, questions (no execution)
+- **🔧 Build** — Execute agreed plans (write, deploy, commit)
 
-mit
+### Versioning
+
+Format: `V{major}.{minor}.{patch}` (e.g., `V0.1.0009`)
+- Patch auto-increments on every git push
+- Agent commits and pushes after every completed step
+
+## License
+
+MIT