DOMAIN:BACKEND¶
OWNER: urszula (Team Alfa), maxim (Team Bravo)
UPDATED: 2026-03-24
SCOPE: all client projects, all teams
AGENTS: urszula (backend lead Alfa), maxim (backend lead Bravo), sandro (hotfix/Zulu)
ALSO_USED_BY: antje (TDD), koen (code quality), boris (DB integration), yoanna (DB integration)
BACKEND:OVERVIEW¶
PURPOSE: define GE's backend development standards, patterns, and guardrails for TypeScript/Node.js APIs
STACK: TypeScript (strict mode) + Node.js + Hono (primary) + Fastify (alternative) + Drizzle ORM + PostgreSQL + Redis + Vitest
RUNTIME: Node.js 20 LTS (minimum), Node.js 22 LTS (preferred)
LANGUAGE: TypeScript 5.x, strict mode always enabled
BACKEND:STACK_DECISIONS¶
PRIMARY_FRAMEWORK: Hono¶
WHY: type-safe, fast (RegExpRouter), edge-ready, built-in RPC client, tiny bundle (~14KB), Web Standards-based
WHEN_FASTIFY: legacy projects already on Fastify, or projects requiring Fastify's plugin ecosystem
WHEN_EXPRESS: never for new projects — Express is 2-3x slower and lacks native TypeScript support
RULE: all new GE client projects use Hono unless client has explicit Fastify requirement
ORM: Drizzle¶
WHY: type-safe SQL, thin abstraction, pure TypeScript schema, fast migrations, ~7.4KB bundle
WHEN_RAW_SQL: complex analytical queries, database-specific features not covered by Drizzle
RULE: never Prisma for new projects — Prisma's custom schema language and heavy runtime are not GE standard
DATABASE: PostgreSQL¶
WHY: ACID, JSONB, full-text search, row-level security, mature ecosystem
VERSION: PostgreSQL 15+ (minimum), PostgreSQL 16+ (preferred)
RULE: PostgreSQL is SSOT — filesystem is optional audit trail only
TESTING: Vitest¶
WHY: fast, native TypeScript, compatible with Jest API, built-in coverage, watch mode
RULE: every backend module has co-located .test.ts files
LOGGING: Pino¶
WHY: fastest Node.js logger (5-10x faster than Winston), JSON-first, child loggers, async I/O
RULE: structured JSON logging in production, pino-pretty in development only
BACKEND:PAGES¶
API_DESIGN: REST patterns, error envelopes, pagination, OpenAPI, Hono specifics
→ domains/backend/api-design.md
HONO_FRAMEWORK: Hono deep dive, middleware, routing, validation, RPC, deployment
→ domains/backend/hono-framework.md
DRIZZLE_ORM: schema, migrations, queries, transactions, connection pooling, pitfalls
→ domains/backend/drizzle-orm.md
TYPESCRIPT_PATTERNS: strict mode, branded types, discriminated unions, Result type, Zod inference
→ domains/backend/typescript-patterns.md
NODE_PRODUCTION: memory, event loop, graceful shutdown, logging, health checks, metrics
→ domains/backend/node-production.md
ARCHITECTURE_PATTERNS: vertical slice, repository, DI, CQRS, event-driven with Redis Streams
→ domains/backend/architecture-patterns.md
THOUGHT_LEADERS: key people, companies, repos, blogs, conference talks
→ domains/backend/thought-leaders.md
PITFALLS: anti-patterns, LLM-specific failure modes, common backend mistakes
→ domains/backend/pitfalls.md
BACKEND:CROSS_REFERENCES¶
SECURITY: domains/security/index.md — OWASP, input validation, auth patterns
PRIVACY: domains/privacy/index.md — GDPR data handling in APIs
PERFORMANCE: domains/performance/index.md — load testing, SLOs, response time budgets
INCIDENT_RESPONSE: domains/incident-response/index.md — sandro's hotfix procedures
TDD: antje writes tests BEFORE implementation — backend agents implement TO the tests
CODE_QUALITY: koen runs linting and static analysis AFTER implementation
BACKEND:AGENT_WORKFLOW¶
FOR urszula AND maxim (BACKEND LEADS)¶
ON_NEW_TASK:
1. READ work package from Faye (Alfa) or Sytske (Bravo)
2. READ relevant domain pages via JIT injection
3. CHECK if TDD tests exist from Antje — if yes, implement TO the tests
4. CHECK architecture-patterns.md for structural decisions
5. IMPLEMENT using Hono + Drizzle + TypeScript strict mode
6. RUN vitest before marking complete
7. WRITE structured completion report
FOR sandro (HOTFIX)¶
ON_HOTFIX:
1. READ incident details from Mira
2. CHECK pitfalls.md for known failure patterns
3. CHECK node-production.md for debugging guidance
4. FIX with minimal blast radius — do not refactor during hotfix
5. ADD regression test
6. MARK complete with root cause analysis
BACKEND:QUALITY_GATES¶
GATE_1: TypeScript compiles with zero errors (strict mode, no any)
GATE_2: All Vitest tests pass (coverage > 80% for new code)
GATE_3: No N+1 queries (check drizzle-orm.md pitfalls)
GATE_4: Input validation on every endpoint (Zod schemas)
GATE_5: Error responses use standard envelope (api-design.md)
GATE_6: Structured logging with correlation IDs (node-production.md)
GATE_7: Graceful shutdown handler present (node-production.md)
GATE_8: No secrets in code (security domain cross-reference)
BACKEND:CONVENTIONS¶
FILE_NAMING: kebab-case for files, PascalCase for types/interfaces, camelCase for functions/variables
DIRECTORY_STRUCTURE: feature-first (vertical slices), not layer-first
IMPORT_STYLE: explicit named imports, no barrel files (index.ts re-exports) in production code
ERROR_HANDLING: Result type pattern preferred over try/catch for business logic (see typescript-patterns.md)
CONFIG: environment variables via validated Zod schema, never raw process.env access
DATES: ISO 8601 strings in API responses, Date objects internally, dayjs for manipulation
BACKEND:AGENTIC_RULES¶
RULE: never generate scaffolding without implementation — every function must have a real body
RULE: never use any type — use unknown and narrow with type guards
RULE: never skip input validation — every endpoint gets a Zod schema
RULE: never hardcode connection strings, ports, or secrets
RULE: never use synchronous file I/O in request handlers
RULE: always handle promise rejections — unhandled rejections crash Node.js
RULE: always use parameterized queries — never string concatenation for SQL
RULE: always set MAXLEN on Redis XADD calls
RULE: always test with realistic data shapes, not empty objects
RULE: when unsure about a pattern, read the relevant domain page before implementing