backend/STANDARDS.md

RMI Development Standards — AI-Forward + Web3 Best Practices

v3 (Jun 21 2026) — Crisis Ops Rebuild: These standards reflect the rebuilt architecture. The legacy 8,475-line _legacy_main.py is frozen; do not edit. New code goes into app/api/v1/ via the aggregator in app/api/v1/__init__.py. See docs/adr/0001-why-fastapi.md and docs/adr/0003-strangler-fig-not-rewrite.md for the architectural decisions.

v3 Hard Rules

1. No mass regex. Each transformation explicit, one-line-per-replace.
2. New files only — never modify the 14 frozen files without explicit un-freeze.
3. Strangler-fig migration: legacy routes stay mounted in main.py until explicitly removed. New v1 routes mount at the same path — first match wins.
4. One-line main.py edits only. Even when adding routes, prefer the app/api/v1/__init__.py aggregator + v1_modules list pattern.
5. No _legacy_main import. The new main.py does not import legacy.
6. Real data flows only. A v1 route that returns 404 / placeholder is not done. Acceptance = a real route serves real data end-to-end.
7. Prometheus metrics required. Every new router emits rmi_requests_total counter (auto via CostTrackingMiddleware).
8. Telegram alerts via @rmialerts only. No personal chat routing. See app/api/v1/admin/alerts_webhook.py.

v3 Modern Builder Bar (14 points)

See ~/.hermes/skills/rmi/modern-builder-compliance/SKILL.md for the full bar. Highlights:

• Async/await for all I/O · Pydantic v2 everywhere · Structured logging
• Type hints on all public functions · No bare except: · Frozen file respect
• Real data acceptance test · Documented in DESIGN.md or relevant ADR
• One concern per file · Tests before merge · No silent failures
• Idempotent endpoints · Pagination on list endpoints · Rate-limited public routes

---

⚠️ FIRST: Read /root/DEVELOPERS.md for canonical paths.

---

BACKEND DEVELOPMENT

Pre-commit checklist (run before every commit):

bash /root/backend/scripts/pre-commit.sh

Checks: Python syntax, hardcoded secrets, env var consistency, stale path references.

Environment variables:

# Auto-generate from Hermes config:
python3 /root/backend/generate_env.py --force
# Then fill in missing values:
nano /root/backend/.env

Live development (no rebuild needed):

# Volume mount means code changes are instant:
docker restart rmi-backend
# Verify:
curl http://localhost:8000/health

Adding new env vars:

1. Add to code: os.getenv("MY_VAR")
2. Add to /root/backend/.env.example with comment
3. Run python3 /root/backend/generate_env.py --force
4. Add to /srv/rugmuncher-backend/docker-compose.yml if container needs it

---

AI AGENT DEVELOPMENT WORKFLOW

This system is designed for AI-assisted development. Here's the stack:

hermes-agent (CLI)
    │
    ├── Terminal tool → docker exec, git, curl, python
    ├── Web tool → API testing, research
    ├── File tool → Edit /root/backend/ directly
    ├── Delegate → Spawn sub-agents for parallel work
    └── Cron jobs → Automated tasks

How Hermes develops the backend:

1. Discover: Reads AGENTS.md in /root/backend/
2. Edit: Patches files directly (volume mount = live)
3. Test: curl localhost:8000/health after changes
4. Rebuild: docker compose build && docker compose up -d
5. Verify: Checks logs, API responses

n8n workflow development:

• UI: http://localhost:5678 (admin / RugMuncher2024)
• Direct DB: sqlite3 /root/n8n-data/database.sqlite
• Import: Copy workflow JSONs into /root/n8n-workflows/
• Test: Check execution history in UI

Orchestrator swarm:

• API: http://localhost:8081
• Health: curl http://localhost:8081/health
• Bots: curl http://localhost:8081/orchestrator/bots
• Create task: POST /orchestrator/task

---

WEB3 SECURITY BEST PRACTICES

Secrets management:

• NO hardcoded secrets in any .py file
• All secrets in /root/.secrets/ or /root/.hermes/.env
• App passwords preferred over account passwords
• Rotate API keys quarterly

Key scanning:

# Run before any commit:
grep -rn '0x[0-9a-fA-F]\{64\}\|sk-[a-zA-Z0-9]\{20,\}' /root/backend/app/ --include='*.py'

RPC security:

• Use dedicated RPC URLs, never public endpoints in production
• Rate limit all on-chain queries
• Cache blockchain data aggressively (Redis)

---

CODE QUALITY

Python:

• Type hints on all public functions
• Docstrings for modules and classes
• Async/await for all I/O operations
• Use Pydantic for data models

TypeScript (Frontend):

• Components in /srv/rugmuncher-backend/rmi-frontend/src/components/
• Services in /srv/rugmuncher-backend/rmi-frontend/src/services/
• Types shared via /srv/rugmuncher-backend/rmi-frontend/src/types.ts

---

MONITORING

Health checks:

# All services:
curl http://localhost:8000/health      # Backend
curl http://localhost:8081/health      # Orchestrator
curl http://localhost:5678/healthz     # n8n
curl http://localhost:9001/api/health  # Listmonk

Logs:

docker logs rmi-backend --tail 50
docker logs rmi-n8n --tail 50
journalctl -u hermes -n 50

Cron jobs:

# List all:
cronjob action='list'
# Check status of specific job:
cronjob action='list'  # look for last_status

---

DEPLOYMENT

Full stack restart:

cd /srv/rugmuncher-backend
docker compose down
docker compose up -d

Rebuild with cache clear:

docker compose build --no-cache backend worker orchestrator
docker compose up -d

Rollback (if something breaks):

# Restore backup:
cp /root/backups/n8n/$(date +%Y-%m)/database.sqlite /root/n8n-data/
docker restart rmi-n8n

# Rebuild from known-good commit:
cd /root/backend && git checkout <commit-hash>
docker restart rmi-backend