Engineering Handbook

Welcome — this is WorkOpti’s source of truth for how we build, review, deploy, and operate this repo. It is a single living document maintained by the Engineering team.

What you’ll find here

The handbook is organized into six tracks:

• Foundations — the principles, architecture, tech stack, and domain language that anchor every decision.
• Engineering — implementation patterns for the backend, frontend, API surface, and tests.
• Operations — infrastructure, CI/CD, environment variables, and database procedures.
• Security & Incidents — the security posture and the incident response playbook.
• AI — how AI capabilities are integrated and operated in production.
• How We Work — workflow, code review, onboarding, and roadmapping.

Suggested reading order

1. Principles — engineering values and how to resolve trade-offs.
2. Architecture — system shape across frontend, backend, data, AI, deployment.
3. Tech Stack — core tools and framework choices.
4. Data Model Glossary — domain language.
5. Backend and Frontend — implementation patterns.
6. API Style Guide — route, schema, pagination, OpenAPI conventions.
7. Testing Guide — test-writing expectations.
8. Security, Infrastructure, CI/CD, Env Vars, Database Ops — operational guardrails.
9. AI Integration and AI Operations — AI architecture and runbooks.
10. Incident Response and On-Call — when things break.

Maintenance

• Update the relevant handbook page in the same PR as meaningful architecture, workflow, security, API, or operational changes.
• Add or update ADRs in backend/py/docs/adr/* when a decision changes system structure or long-term constraints.
• Review handbook pages at least quarterly and refresh the Last reviewed marker when the content is checked.
• If CLAUDE.md (agent-facing) and this handbook (team-facing) disagree, update whichever is stale.