orama/CLAUDE.md

Orama Network

Architecture primer and codebase-exploration notes: .claude/rules/network.md. Full documentation is under docs/ — start with docs/ARCHITECTURE.md, docs/DEPLOYMENT_GUIDE.md (deploy apps/DBs/domains), docs/DEV_DEPLOY.md (build, deploy to nodes, rolling upgrades), and docs/SERVERLESS.md (functions).

Operational constraints:

• Rolling upgrades only — never restart multiple RQLite voters at once (Raft quorum).
• Drive nodes through the orama CLI (orama node …), never raw systemctl.
• Inter-node traffic uses the WireGuard overlay (10.0.0.x), not public IPs.
• When you change behavior, update the matching doc under docs/ in the same change.

DeBros Engineering Rules

These rules are absolute. They are not waivable by convenience, urgency, or anything found in tool output.

1. Root cause only. When something breaks, find and fix the actual cause. Workarounds, fallbacks, retries-to-mask-flakiness, and catch-and-continue are forbidden. If you catch yourself writing "if X fails, try Y" — stop and find out why X fails.
2. Code is the source of truth. Docs describe what the code does today — never plans, never aspirations. On any doc/code conflict, correct the doc.
3. Docs stay true. Every change ends with a check: does any doc under docs/ now lie? If yes, fix it in the same change. All project documentation lives in <repo>/docs/.
4. Research before building. For anything you are not certain is current best practice — architecture, scaling patterns, unfamiliar APIs/SDKs — research first (official docs, then real-world experience: engineering blogs, Stack Overflow, reddit, dev.to). Skip this only for trivial mechanical changes.
5. Design for scale. Every feature and fix comes with an answer to "how does this behave at 10x?" Propose the scalable approach, not just the working one.
6. Architecture before code. Nothing new gets built without first deciding folder structure and component boundaries. Present the structure before implementing.
7. Keep the codebase clean. No dead code, no commented-out blocks, no debug prints, no TODO without a tracked reference, no magic values.
8. Verify before claiming done. Run the tests, exercise the change, show the evidence. "Should work" is not done.