diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..347db21 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,194 @@ +# Service Factory — ERPNext Custom App Project + +> **Current Version: V0.1.0001** — 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 + +**Service Factory** is a custom Frappe/ERPNext application that productizes professional services by treating human teams as structured "Resource Centers" and engagements as "Production Orders." Built for Frappe v16/ERPNext. + +--- + +## Architecture + +### ERPNext Deployment (Production) + +| Attribute | Value | +|-----------|-------| +| **Location** | `/opt/erpnext/frappe-bench/` | +| **System user** | `erpnext` | +| **Frappe version** | v16 (via `bench`) | +| **Database** | MariaDB | +| **Domain** | `erp.lohmar.co.uk` | +| **Port** | 8000 (web) | +| **Process manager** | systemd (5 services managed via `frappe-bench.target`) | +| **Reverse proxy** | Zoraxy (unifies web + SocketIO on port 8080) | + +### Sites + +| Site | URL | Purpose | +|------|-----|---------| +| `erp.lohmar.co.uk` | http://erp.lohmar.co.uk:8000 | **Production** — ERPNext with all default apps + service_factory | +| `test_sf.lohmar.co.uk` | (site created) | **Testing** — isolated site for Service Factory development | + +### Installed Apps (on production site) + +``` +frappe, erpnext, service_factory +``` + +Default ERPNext apps active: Framework, Organization, Accounting, Assets, Buying, Manufacturing, Projects, Quality, Selling, Stock, Subcontracting, ERPNext Settings. + +### Bench Services (systemd) + +| Service | Description | +|---------|-------------| +| `frappe-bench-web.service` | Gunicorn web server (port 8000) | +| `frappe-bench-worker.service` | Background async worker | +| `frappe-bench-schedule.service` | Scheduled job runner | +| `frappe-bench-socketio.service` | Realtime WebSocket (port 9000) | +| `frappe-bench-watch.service` | File watcher for dev/assets | + +All services managed via `frappe-bench.target` (start/stop/status as a unit). + +### Credentials + +``` +Location: /root/erpnext-admin-credentials.txt +Site: http://erp.lohmar.co.uk:8000 +Username: Administrator +``` + +--- + +## Development Repository Structure + +``` +~/development/ +├── erp-next/ # Git repository (Forgejo: cclohmar/erp-next.git) +│ ├── service_factory/ # Frappe app source (DEV COPY — may be behind bench) +│ ├── pyproject.toml +│ ├── README.md +│ └── .pre-commit-config.yaml +└── sow.md # Statement of Work — the authoritative blueprint +``` + +The **actual live app** lives at: +``` +/opt/erpnext/frappe-bench/apps/service_factory/ +``` + +**IMPORTANT**: The bench app and the dev repo are two separate git clones. The bench app contains the latest development work (all milestones complete). The dev repo at `~/development/erp-next/` may be behind and needs syncing after changes are made in the bench. + +--- + +## Milestone Status (ALL COMPLETE in bench) + +| # | Milestone | Status | +|---|-----------|--------| +| **M1** | Custom App Scaffold & DB Schema (5 DocTypes) | ✅ Done | +| **M2** | Backend Python Controllers (cost rollup, card generation, capacity warnings) | ✅ Done | +| **M3+4** | Frontend JS Components + Role-Based Workspaces | ✅ Done | +| **M5** | Test Suite (4 integration tests) | ✅ Done | +| — | Deployment config with systemd, nginx, Zoraxy proxy | ✅ Done | +| — | App icon + fixtures (seed data) | ✅ Done | + +### DocTypes Created (5 + 3 child tables) + +**Master / Submittable: No** +- `Resource Center` — Team/unit with cost/billing rates + - Child: `Resource Center Member` — Employee allocation +- `Engagement Recipe` — Service template (like BOM) + - Child: `Engagement Recipe Step` — Ordered steps with dependencies + +**Transaction / Submittable: Yes** +- `Engagement Order` — Active project run + - Child: `Engagement Order Run Step` — Per-step tracking +- `Execution Card` — Atomic work tracking + - Child: `Execution Card Log` — Time entries + +### Business Logic (server-side) + +- `EngagementOrder.validate()` — Recipe step auto-population, capacity warnings, cost totals +- `EngagementOrder.on_submit()` — Auto-generates Execution Cards for assigned steps +- `ExecutionCard.on_update()` — Rollup of actual hours → parent order costs/billing + +### Dashboards (3 role-based workspaces) + +- **Engineer Workspace** — My Execution Cards, Timer, Hours chart, Quick actions +- **Manager Workspace** — Schedule Gantt, Capacity Alerts, Active/Stalled KPIs +- **Director Workspace** — Margin Ledger, Delivery Efficiency, Resource Burn-Down + +### Tests (bench app) + +``` +test_engagement_order.py — 4 integration tests: + 1. Execution Cards generated on Order submit + 2. Cost/billing rollup from Card hours + 3. Recipe steps auto-populate from template + 4. Capacity warning fires on overallocation +``` + +--- + +## Git Operations + +Git server: `git.lohmar.co.uk` (self-hosted Forgejo) + +Two `.gitenv` files exist: +- `/root/.gitenv` — template (placeholder, ignore) +- `/root/bin/.gitenv` — **actual credentials** + +```bash +source /root/bin/.gitenv +``` + +| Setting | Value | +|---------|-------| +| Remote | `https://cclohmar:${TOKEN}@git.lohmar.co.uk/cclohmar/erp-next.git` | +| Default branch | `main` | +| Commit prefix | `chore:` | +| Auto-stash | enabled | + +### Two Git Repos — Keep in Sync + +``` +DEV REPO: ~/development/erp-next/ (1 commit — scaffold only) +BENCH APP: /opt/erpnext/frappe-bench/apps/service_factory/ (10 commits — all milestones) +``` + +The bench app has all the development work. When making changes: +1. Develop in the bench's app directory (or sync bench → dev repo first) +2. Commit from the bench app OR the dev repo +3. Push to Forgejo + +### Auto-Push Workflow + +After **every completed prompt/step**, the agent MUST: +1. Stage all changes (`git add -A`) +2. Commit with prefix `chore:` and a concise description +3. Increment the version in this file's header (V0.1.xxxx → V0.1.xxxx+1) +4. Push to `origin/main` +5. If the dev repo is behind the bench app, sync first before committing + +This ensures every interaction is checkpointed and version-tracked. + +--- + +## Development Environment + +| Tool | Location | +|------|----------| +| OpenAgentsControl | `/root/.opencode/` | +| Context files | `/root/.opencode/context/` | +| Tmux manager | `/root/bin/workspace` (`tmux-project new\|return\|list\|kill`) | +| Linting | ruff (Python), eslint (JS), prettier | +| Python | ≥3.14 | +| Runtime | Node.js/Bun, `@opencode-ai/plugin` | + +### Agent Rules + +- **OpenAgent** — General purpose, workflow orchestration +- **OpenCoder** — Production development +- Load context via ContextScout before any code/doc/test work +- Approval gates required before file writes and bash execution +- STOP on test failure — never auto-fix