Backend Design

<domain_overview>

Backend Design System

Philosophy: The Backend is the Fortress. Logic is Law. Latency is the Enemy.

Core Principle: ISOLATE features. TRUST no one. SCALE linearly.

ANTI-HAPPY PATH MANDATE (CRITICAL): Never assume the ideal scenario. AI-generated code often fails by ignoring edge cases and failure modes. For every business logic slice, you MUST document and test at least three failure scenarios: Race Conditions, Data Integrity violations (e.g., unique constraint overlaps), and Boundary failures. Reject any implementation that only covers the 'Happy Path'. Engineering is the art of handling what shouldn't happen. </domain_overview>

<architectural_protocols>

🚀 ELITE TIER KNOWLEDGE (ARCHITECTURAL PROTOCOLS)

0. The "Vertical Slice" Law (The Anti-Layer Mandate)

CRITICAL: You are FORBIDDEN from creating "Horizontal Layers" (Controllers, Services, Repositories) as primary folders.

The "Feature-First" Protocol: Code must be organized by BUSINESS CAPABILITY, not technical role. 1. The Slice: A single directory (e.g., features/create-order/) contains EVERYTHING needed for that feature:

• handler.ts (Controller)
• logic.ts (Domain/Service)
• schema.ts (DTO/Validation)
• db.ts (Data Access)

2. The Benefit: Changing a feature requires touching only ONE folder. No "Shotgun Surgery" across 5 layers. 3. Shared Kernel: Only truly generic code (Logging, Auth Middleware, Database Connection) goes into shared/.

1. The "Modular Monolith" Mandate

• Microservices Ban: Do NOT start with microservices. Start with a Modular Monolith.
• Modulith Rules:
• Modules must be isolated (like internal microservices).
• Modules communicate via Events (Sub-Process or Message Bus), NEVER by importing another module's code directly.
• The Outbox Pattern (Guaranteed Delivery):
• Problem: If DB commit succeeds but Event Bus fails, the system is inconsistent.
• Mandate: Write events to an outbox table in the SAME transaction as the data change.
• Relay: A background worker pushes outbox entries to the Message Bus (RabbitMQ/Kafka).
• Data Sovereignty: Module A cannot query Module B's tables. It must ask Module B via API/Event.

2. The "Zero Trust" Security Protocol

Detailed protocols: See security-protocols.md

Quick Rules: 1. Strict Serialization: NEVER return raw DB entities → Use ResponseDTO 2. Validation at Gate: Schema validation (Zod/Pydantic) BEFORE logic 3. Token Sovereignty: PASETO v4 > JWT (Ed25519 if JWT forced) </architectural_protocols>

<reliability_contracts>

🏗️ Reliability & Performance Contracts

3. The "Sub-100ms" Performance Mandate

• The Latency Budget: P50 < 100ms. P99 < 500ms.
• UUIDv7 (The Time-Lord Rule):
• Ban: Never use UUIDv4 (Random) for Primary Keys. It fragments B-Tree indexes.
• Mandate: Use UUIDv7 (Time-ordered). It enables clustered index locality (fast inserts) like integers, with the uniqueness of UUIDs.
• N+1 Assassin:
• Check: Always inspect ORM queries. Loops triggering DB calls are a "Level 0" error.
• Fix: Use DataLoader pattern or explicit JOIN loading.

4. API Reliability Contracts

• RFC 7807 (Problem Details):
• Ban: returning { "error": "Something went wrong" }.
• Mandate: Return standard Problem JSON:

        {
          "type": "https://api.myapp.com/errors/insufficient-funds",
          "title": "Insufficient Funds",
          "status": 403,
          "detail": "Current balance is 10.00, required is 15.00",
          "instance": "/transactions/12345"
        }

• Idempotency Keys:
• Rule: All critical POST/PATCH (Money, State Change) must accept an Idempotency-Key header.
• Logic: If key exists in Cache (24h TTL), return stored response without re-executing logic.

</reliability_contracts>

<database_integrity>

🗄️ Database Integrity & Design

5. Database Integrity & Design

• Hard Constraints: Application-level checks are "Suggestions". Database Constraints (Foreign Keys, Unique Indexes, Check Constraints) are "Laws".
• Cursor Pagination:
• Ban: OFFSET / LIMIT on large tables (O(N) performance degradation).
• Mandate: Cursor-based pagination (WHERE created_at < cursor LIMIT 20).
• Migration Discipline:
• Never alter a column in a way that locks the table for >1s.
• Use "Expand and Contract" pattern for breaking changes.
• Concurrency Control:
• Problem: Two users update the same record. The last one wipes the first.
• Mandate: Use Optimistic Locking. Add a version (int) column.
• Logic: Update WHERE id = X AND version = Y. If 0 rows affected, throw StaleObjectException.

6. AI & Vector Readiness

• Semantic Storage: Backend must be ready to store embeddings (Vector Types).
• Guardrails: Output from LLMs must be sanitized and structure-checked on the server side before returning to frontend.

</database_integrity>

<observability>

👁️ Observability & Monitoring (The "Glass Box" Protocol)

7. Structured Logging Only

• Ban: console.log("User updated"). String logs are useless for machines.
• *Mandate: JSON Logs with correlation IDs. { "level": "info", "event": "user_updated", "user_id": "u7-...", "trace_id": "..." }.

8. Distributed Tracing (OpenTelemetry)

• Every request MUST carry a traceparent header.
• Spans must cover: DB Queries, External API Calls, and Redis operations.

9. Health Checks

• Liveness (/health/live): "Am I running?" (Instant, no checks).
• Readiness (/health/ready): "Can I take traffic?" (Check DB/Redis connection).

</observability>

<resilience>

🛡️ Resilience Patterns (The "Anti-Fragile" Mandate)

10. Circuit Breakers

• Wrap ALL external calls (Payment Gateways, 3rd Party APIs) in a Circuit Breaker.
• Logic: After 5 failures, fail fast for 30s. Don't drown the downstream service.

11. Rate Limiting

• Protect every public endpoint with a Token Bucket rate limiter (Redis-backed).
• Differentiate limits by User Role (Anon: 60/min, Pro: 1000/min).

</resilience>

<workflow_rules>

🔧 Workflow Rules

1. The Pre-Flight Checklist

0. Environment Hardening:

• Verify all process.env variables at startup using a schema (e.g., t3-env or envalid). If a key is missing, crash immediately. Do not start the server in an undefined state.

Before writing a single handler: 1. Define the DTOs: Request Schema (Zod) and Response Schema. 2. Define the Error States: What can go wrong? (404, 409, 429). 3. Define the Data Access: What is the most efficient SQL query?

2. The "No Magic" Rule

• Avoid "Magical" ORM features (Lazy Loading, Auto-Saving context).
• Prefer Explicit over Implicit. "Write the SQL (or Query Builder) if the ORM hides expensive logic."

3. Testing Pyramid

1. Unit: Test Domain Logic in isolation (mock DB). 2. Integration: Test Feature Slice with a REAL containerized DB (Testcontainers). 3. E2E: Test critical flows from the "Outside". </workflow_rules>

<audit_and_reference>

📂 Cognitive Audit Cycle

Before committing code: 1. Is the endpoint under a feature slice? (Not in a generic controller folder). 2. Is Input Validated with a Schema? (Zero Trust). 3. Are DB Indexes used? (Run EXPLAIN ANALYZE). 4. Is the Primary Key UUIDv7? (Index Perf). 5. Are secrets managed properly? (No hardcoded strings).

---

🔗 CROSS-SKILL INTEGRATION

Command: Use these skills to architect "Fortress-Level" backend systems.

</audit_and_reference>

Backend Security Protocols

Reference file for `@backend-design` - Load when building APIs and services.

---

🛡️ Zero Trust Architecture

Core Principle: Trust nothing. Verify everything.

---

🔐 Input Validation (Gate)

Mandatory for ALL endpoints:

// ✅ CORRECT - Validate at the gate
const CreateUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8).max(72), // bcrypt limit
  name: z.string().min(1).max(100)
}).strict(); // Strip unknown keys

// Use in handler
const validated = CreateUserSchema.parse(req.body);

Rules:

• Validate BEFORE any logic executes
• Use .strict() to reject unknown fields
• Set reasonable length limits

---

🗄️ SQL Injection Prevention

Safe Patterns:

// ❌ DANGEROUS
db.query(`SELECT * FROM users WHERE id = '${userId}'`);

// ✅ SAFE - Parameterized
db.query('SELECT * FROM users WHERE id = $1', [userId]);

// ✅ SAFE - ORM
User.findOne({ where: { id: userId } });

---

🔑 Authentication Tokens

PASETO > JWT (2025 Standard):

// PASETO v4 (recommended)
import { V4 } from 'paseto';

const token = await V4.sign(
  { sub: userId, exp: '1h' },
  privateKey
);

If JWT forced (external provider):

• Use RS256 or EdDSA only
• NEVER HS256 with weak secret
• NEVER allow alg: none

---

🚪 CORS Configuration

Strict Configuration:

// ✅ CORRECT
const corsOptions = {
  origin: ['https://app.example.com', 'https://admin.example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  credentials: true,
  maxAge: 86400
};

// ❌ DANGEROUS
const corsOptions = {
  origin: '*' // NEVER in production
};

---

🚦 Rate Limiting

Required on ALL public endpoints:

// Token bucket with Redis
const rateLimiter = rateLimit({
  store: new RedisStore({ client: redis }),
  windowMs: 60 * 1000, // 1 minute
  max: (req) => req.user ? 100 : 20, // Authenticated vs anon
  standardHeaders: true,
  legacyHeaders: false
});

Limits by endpoint type:

---

🔒 Secrets Management

Rules: 1. NEVER hardcode secrets 2. Validate env vars at startup 3. Use secret managers in production (Vault, AWS Secrets)

// Validate at startup
import { z } from 'zod';

const EnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  API_KEY: z.string()
});

// Crash immediately if invalid
const env = EnvSchema.parse(process.env);

---

📊 Security Headers

Required headers:

app.use((req, res, next) => {
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('X-XSS-Protection', '0'); // Modern browsers don't need
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
  res.setHeader('Content-Security-Policy', "default-src 'self'");
  next();
});

---

🔗 Cross-Skill References

• @clean-code - General security defaults, dependency audit
• @frontend-design - CSP, CORS coordination
• @debug-mastery - Security incident logging
• @verification-mastery - Security test verification