EGCA Engineering Handbook
Opinionated defaults for building things here. For juniors and mid-level engineers who need a quick, consistent answer without pinging a senior.
Use the defaults. Deviate when you have a real reason and a lead agrees. Don't silently diverge.
Quick decision tree
New project? Answer three questions:
| Question | If yes → | If no ↓ |
|---|---|---|
| 1. Is it internal / admin? |
Next.js + Postgres + Vercel + Drizzle + Entra SSO (@egca.io) → Next.js Playbook | Continue |
| 2. Is it a small / MVP client app? |
Next.js monolith + Clerk + Resend
→ Next.js Playbook | Continue |
| 3. Is it large / multiple consumers? |
Next.js + 1–3 split services (semi-microservices)
→ Backend API Playbook | See other shapes below |
Other shapes:
- Mobile — Expo + React Native → Mobile & CLI Playbook
- Data / ML / AI — Python + Postgres + pgvector → Data / ML / AI Playbook
- CLI / script / cron — tsx + commander, or Python + typer → Mobile & CLI Playbook
Still unsure? Ask a lead. Don't guess.
New here?
Start with Onboarding. It covers the first day, the first week, and who to ask for what. Then read the foundations below in order.
Foundations
The full reference. Read top-to-bottom in your first week; come back for specifics later.
Picking and building
- 1. Stack Selection — picking language, framework, hosting.
- 2. Architecture — monolith vs split, DB, auth, ORM.
How we work
- 3. Git Workflow — branches, commits, rebasing, recovery.
- 4. Dev Workflow — CI, envs, style, deps.
- 5. Code Review — both sides of the PR.
- 6. AI-Assisted Coding — using LLMs without getting lazy.
Ship with confidence
- 7. Testing — mandatory test files per project.
- 8. Deployment & Ops — Vercel / Azure / VPS.
- 9. Prototype vs Production — harden checklist.
Playbooks
Per-project-type guides with concrete defaults.
Next.js App
Internal tools and client web apps. App Router only.
Backend API
Standalone services split from a Next.js monolith.
Data / ML / AI
LLM features, pipelines, evals, retrieval.
Mobile & CLI
Expo React Native apps and internal CLIs.
Hard rules
Non-negotiable company-wide defaults. Deviation needs a senior's sign-off.
| Area | Rule |
|---|---|
| Database | Postgres only. Local on Docker. Preview on Neon/Supabase OK. Production always Azure Postgres. No NoSQL. No Firebase. |
| Auth (internal / admin) | Microsoft Entra, restricted to @egca.io tenant. Single-tenant app registration + domain check. |
| Auth (client-facing) | Clerk (default) or Auth.js. Never Entra — clients aren't on our tenant. |
| Testing | Tests required in every project. No test files in a PR = PR blocked. |
| Secrets | Vercel env / Azure Key Vault. Never in git, Teams, or screenshots. |
| Resend for external / transactional. Entra + Microsoft Graph for internal (sends from company mailbox). | |
| Monitoring | Error tracking (Datadog, or Azure Application Insights on Azure-hosted apps) wired on every app from day one — not after the first incident. |
How to disagree with this handbook
- Write down why the default doesn't fit your case — one paragraph.
- Ping a senior in the PR description or a short Teams thread.
- If they agree, note the deviation in the project README so the next person isn't confused.
- If the deviation happens twice in different projects, the handbook is probably wrong. Propose an edit.
Silent deviation is the worst option. Takes five minutes to explain, saves months of inconsistency.