Technical Constitution

The Constitution: Technical Preference Universal Principles

⚖️ CRITICAL GOVERNANCE NOTICE

CRITICAL: BEFORE doing ANYTHING else, Read and Comprehend this document COMPLETELY.

MANDATORY COMPLIANCE CHECK:

Before executing your task, you must perform a "Constitution Lookup":

1. IDENTIFY the domain of your task (e.g., API, DB, Auth, logging, etc.).
2. SEARCH the relevant sections (e.g., grep "API Design").
3. REVIEW Critical Constraints table for domain
4. VERIFY your plan against the discipline and constraints before proceeding.

1. The Supremacy Clause & Conflict Resolution

When directives conflict or seem impossible to satisfy simultaneously, follow this precedence:

1. Security Principles [Non-Negotiable]

   • OWASP Top 10 compliance
   • Input validation and sanitization
   • Authentication and authorization
   • Secrets management
   • No information leakage
   • Action: Security ALWAYS wins. Refactor other requirements to satisfy security.

2. Testability & Modularity [Structural Law]

   • I/O isolation (dependencies mockable in tests)
   • Pure business logic (no side effects in core logic)
   • Clear module boundaries with contracts
   • Action: If code cannot be unit tested without external dependencies, refactor to add abstraction layer.

3. Error Handling Standards [Reliability Law]

   • No silent failures
   • Correlation IDs required
   • JSON envelope format
   • Resource cleanup in all paths
   • Action: All error paths must be explicit. No exceptions.

4. Language Idioms [Implementation Preference]

   • Use native patterns (defer, RAII, context managers)
   • Follow community conventions
   • Leverage standard library
   • Action: Implement above laws idiomatically, don't blindly copy other languages.

5. Performance Optimizations [Measure First]

   • Appropriate data structures
   • Profile before optimizing
   • Caching strategies
   • Action: Only optimize with measured bottlenecks. Correctness > speed

Escalation Protocol

If following a directive is impossible:

1. STOP coding immediately
2. Document the conflict:
   • Which directives conflict?
   • Why is compliance impossible?
   • What are the tradeoffs?
3. Propose alternatives:
   • Option A: [approach + which rules satisfied/violated]
   • Option B: [approach + which rules satisfied/violated]
   • ...
4. ASK human for decision
   • Present the precedence hierarchy
   • Recommend least-harmful deviation option with justification based on hierarchy
   • Wait for explicit approval

CRITICAL: NEVER silently violate, If following directive is impossible, STOP and ask human

Example:

Scenario 1: Framework Requires Inheritance (Architecture vs Language Idiom)

• Conflict: Django ORM requires model inheritance, but domain must be pure
• Hierarchy: Architecture (Level 2) > Framework idiom (Level 4)
• Resolution: Create Database Model (inherits ORM) + Pure Domain Entity + Mapper pattern
• PROCEED: Architecture wins

Scenario 2: Performance vs Security

• Conflict: Caching would speed up response but contains PII
• Hierarchy: Security (Level 1) > Performance (Level 5)
• Resolution: Sanitize PII before caching OR skip caching for PII endpoints
• PROCEED: Security wins

Scenario 3: Testing Pure Functions with Time Dependencies

• Conflict: Domain needs current timestamp but should be pure
• Hierarchy: Architecture purity (Level 2) maintained via Time Port (Level 4 idiom)
• Resolution: Inject Clock/Time interface as driven port, mock in tests
• PROCEED: Both satisfied through proper port design

2. Critical Constraints Manifest (Context Triggers)

Agent Note: If the user query touches on these specific topics, prioritize the following internal rules over general knowledge. These are the High-Priority Constraints. Violating these is an automatic failure.

3. Table of Contents

Agent Note: Refer to the sections below for detailed implementation rules on all 16 topics.

• The Constitution: Technical Preference Universal Principles
  • 1. The Supremacy Clause & Conflict Resolution
    • Escalation Protocol
      • Example:
  • 2. Critical Constraints Manifest (Context Triggers)
  • 3. Table of Contents
  • Architectural Patterns - Testability-First Design
    • Core Principle
    • Universal Architecture Rules
      • Rule 1: I/O Isolation
      • Rule 2: Pure Business Logic
      • Rule 3: Module Boundaries
      • Rule 4: Dependency Direction
      • Layout Examples
    • Pattern Discovery Protocol
    • Testing Requirements
    • Language-Specific Idioms
    • Enforcement Checklist
    • Related Principles
  • Core Design Principles
    • SOLID Principles
    • Essential Design Practices
    • Code Organization Principles
  • Error Handling Principles
    • Error Categories
    • Recoverable vs Non-Recoverable Errors
    • Universal Error Handling Principles
    • Application Error Object (Internal/Log Format)
    • Error Handling Checklist
    • Related Principles
  • Concurrency and Threading Principles
    • When to Use Concurrency
    • Universal Concurrency Principles
    • Concurrency Models by Use Case
    • Testing Concurrent Code
    • Related Principles
  • Resource and Memory Management Principles
    • Universal Resource Management Rules
    • Memory Management by Language Type
    • Related Principles
  • API Design Principles
    • RESTful API Standards
    • Related Principles
  • Testing Strategy
    • Test Pyramid
    • Test-Driven Development (TDD)
    • Test Doubles Strategy
    • Test Organization
      • A. Backend (Go - Feature-Based)
      • B. Frontend (Vue - Feature-Sliced)
      • C. Monorepo (Multi-Stack)
    • Test Quality Standards
    • Related Principles
  • Configuration Management Principles
    • Separation of Configuration and Code
    • Configuration Validation
    • Configuration Hierarchy
    • Configuration Organization
    • Related Principles
  • Performance Optimization Principles
    • Measure Before Optimizing
    • Choose Appropriate Data Structures
    • Avoid Premature Abstraction
    • Optimization Techniques
  • Data Serialization and Interchange Principles
    • Validate at System Boundaries
    • Handle Encoding Explicitly
    • Serialization Format Selection
    • Security Considerations
    • Related Principles
  • Logging and Observability Principles
    • Logging Standards
      • Log Levels (Standard Priority)
      • Logging Rules
      • Language-Specific Implementations
        • Go (using slog standard library)
        • TypeScript/Node.js (using pino)
      • Python (using structlog)
      • Log Patterns by Operation Type
        • API Request/Response
        • Database Operations
        • External API Calls
        • Background Jobs
        • Error Scenarios
      • Environment-Specific Configuration
      • Testing Logs
      • Monitoring Integration
      • Checklist for Every Feature
    • Observability Strategy
    • Related Principles
  • Code Idioms and Conventions
    • Universal Principle
    • Idiomatic Code Characteristics
    • Avoid Cross-Language Anti-Patterns
  • Dependency Management Principles
    • Version Pinning
    • Minimize Dependencies
    • Organize Imports
    • Avoid Circular Dependencies
  • Command Execution Principles
    • Security
    • Portability
    • Error Handling
    • Related Principles
  • Documentation Principles
    • Self-Documenting Code
    • Documentation Levels
  • Security Principles
    • OWASP Top 10 Enforcement
    • Authentication & Authorization
    • Input Validation & Sanitization
    • Logging & Monitoring (Security Focus)
    • Secrets Management
    • Related Principles

Architectural Patterns - Testability-First Design

Core Principle

All code must be independently testable without running the full application or external infrastructure.

Universal Architecture Rules

Rule 1: I/O Isolation

Problem: Tightly coupled I/O makes tests slow, flaky, and environment-dependent.

Solution: Abstract all I/O behind interfaces/contracts:

• Database queries
• HTTP calls (to external APIs)
• File system operations
• Time/randomness (for determinism)
• Message queues

Implementation Discovery:

1. Search for existing abstraction patterns: find_symbol("Interface"), find_symbol("Mock"), find_symbol("Repository")
2. Match the style (interface in Go, Protocol in Python, interface in TypeScript)
3. Implement production adapter AND test adapter

Example (Go):

// Contract (port)
type UserStore interface {
  Create(ctx context.Context, user User) error
  GetByEmail(ctx context.Context, email string) (*User, error)
}

// Production adapter
type PostgresUserStore struct { /* ... */ }

// Test adapter
type MockUserStore struct { /* ... */ }

Example (TypeScript/Vue):

// Contract (service layer)
export interface TaskAPI {
  createTask(title: string): Promise<Task>;
  getTasks(): Promise<Task[]>;
}

// Production adapter
export class EncoreTaskAPI implements TaskAPI { /* ... */ }

// Test adapter (vi.mock or manual)
export class MockTaskAPI implements TaskAPI { /* ... */ }

Rule 2: Pure Business Logic

Problem: Business rules mixed with I/O are impossible to test without infrastructure.

Solution: Extract calculations, validations, transformations into pure functions:

• Input → Output, no side effects
• Deterministic: same input = same output
• No I/O inside business rules

Examples:

// ✅ Pure function - easy to test
func calculateDiscount(items []Item, coupon Coupon) (float64, error) {
// Pure calculation, returns value
}

// ❌ Impure - database call inside
func calculateDiscount(ctx context.Context, items []Item, coupon Coupon) (float64, error) {
validCoupon, err := db.GetCoupon(ctx, coupon.ID) // NO!
}

Correct approach:

// 1. Fetch dependencies first (in handler/service)
validCoupon, err := store.GetCoupon(ctx, coupon.ID)

// 2. Pass to pure logic
discount, err := calculateDiscount(items, validCoupon)

// 3. Persist result
err = store.SaveOrder(ctx, order)

Rule 3: Module Boundaries

Problem: Cross-module coupling makes changes ripple across codebase.

Solution: Feature-based organization with clear public interfaces:

• One feature = one directory
• Each module exposes a public API (exported functions/classes)
• Internal implementation details are private
• Cross-module calls only through public API

Directory Structure (Language-Agnostic):

/task

- public_api.{ext}      # Exported interface
- business.{ext}        # Pure logic
- store.{ext}           # I/O abstraction (interface)
- postgres.{ext}        # I/O implementation
- mock.{ext}            # Test implementation
- test.{ext}            # Unit tests (mocked I/O)
- integration.test.{ext} # Integration tests (real I/O)

Go Example:

/apps/backend/task

- task.go               # Encore API endpoints (public)
- business.go           # Pure domain logic
- store.go              # interface UserStore
- postgres.go           # implements UserStore
- task_test.go          # Unit tests with MockStore
- task_integration_test.go # Integration with real DB

Vue Example:

/apps/frontend/src/features/task

- index.ts              # Public exports
- task.service.ts       # Business logic
- task.api.ts           # interface TaskAPI
- task.api.encore.ts    # implements TaskAPI
- task.store.ts         # Pinia store (uses TaskAPI)
- task.service.spec.ts  # Unit tests (mock API)

Rule 4: Dependency Direction

Principle: Dependencies point inward toward business logic.

┌─────────────────────────────────────┐
│  Infrastructure Layer               │
│  (DB, HTTP, Files, External APIs)   │
│                                     │
│  Depends on ↓                       │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│  Contracts/Interfaces Layer         │
│  (Abstract ports - no implementation)│
│                                     │
│  Depends on ↓                       │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│  Business Logic Layer               │
│  (Pure functions, domain rules)     │
│  NO dependencies on infrastructure  │
└─────────────────────────────────────┘

Never:

• Business logic imports database driver
• Domain entities import HTTP framework
• Core calculations import config files

Always:

• Infrastructure implements interfaces defined by business layer
• Business logic receives dependencies via injection

Package Structure Philosophy:

• Organize by FEATURE, not by technical layer
• Each feature is a vertical slice
• Enables modular growth, clear boundaries, and independent deployability

Universal Rule: Context → Feature → Layer

1. Level 1: Repository Scope (Conditional)

• Scenario A (Monorepo/Full-Stack): Root contains apps/ grouping distinct applications (e.g., apps/backend, apps/web).
• Scenario B (Single Service): Root IS the application. Do not create apps/backend wrapper. Start directly at Level 2.

2. Level 2: Feature Organization

• Rule: Divide application into vertical business slices (e.g., user/, order/, payment/).
• Anti-Pattern: Do NOT organize by technical layer (e.g., controllers/, models/, services/) at the top level.

Layout Examples

A. Standard Single Service (Backend, Microservice or MVC)

  apps/  
    task/                       # Feature: Task management    
      task.go                      # API handlers (public interface)
      task_test.go                 # Unit tests (mocked dependencies)
      business.go                  # Pure business logic
      business_test.go             # Unit tests (pure functions)
      store.go                     # interface TaskStore
      postgres.go                  # implements TaskStore
      postgres_integration_test.go # Integration tests (real DB)
      mock_store.go               # Test implementation
    migrations/
      001_create_tasks.up.sql
    order/                      # Feature: Order management  
      ...

B. Monorepo Layout (Multi-Stack): *Use this structure when managing monolithic full-stack applications with backend, frontend, mobile in a single repository. Clear Boundaries: Backend business logic is isolated from Frontend UI logic, even if they share the same repo

  apps/
    backend/                        # Backend application source code  
        task/                       # Feature: Task management  
          task.go                      # API handlers (public interface)
          ...   
        order/                      # Feature: Order management  
        ...
    frontend/                       # Frontend application source code
      assets/                       # Fonts, Images
      components/                   # Shared Component (Buttons, Inputs) - Dumb UI, No Domain Logic
        BaseButton.vue
        BaseInput.vue
      layouts/                      # App shells (Sidebar, Navbar wrappers)
      utils/                        # Date formatting, validation helpers
      features/                     # Business Features (Vertical Slices)
        task/                       # Feature: Task management
          TaskForm.vue              # Feature-specific components
          TaskListItem.vue          
          TaskFilters.vue           
          index.ts                  # Public exports
          task.service.ts           # Business logic
          task.api.ts               # interface TaskAPI
          task.api.encore.ts        # Production implementation
          task.store.ts             # Pinia store
        order/
      ...

This Feature/Domain/UI/API structure is framework-agnostic. It applies equally to React, Vue, Svelte, and Mobile (React Native/Flutter). 'UI' always refers to the framework's native component format (.tsx, .vue, .svelte, .dart).

Pattern Discovery Protocol

Before implementing ANY feature:

1. Search existing patterns (MANDATORY):

find_symbol("Interface") OR find_symbol("Repository") OR find_symbol("Service")

2. Examine 3 existing modules for consistency:

• How do they handle database access?
• Where are pure functions vs I/O operations?
• What testing patterns exist?

3. Document pattern (80%+ consistency required):

• "Following pattern from [task, user, auth] modules"
• "X/Y modules use interface-based stores"
• "All tests use [MockStore, vi.mock, TestingPinia] pattern"

4. If consistency <80%: STOP and report fragmentation to human.

Testing Requirements

Unit Tests (must run without infrastructure):

• Mock all I/O dependencies
• Test business logic in isolation
• Fast (<100ms per test)
• 85%+ coverage of business paths

Integration Tests (must test real infrastructure):

• Use real database (Testcontainers, Firebase emulator)
• Test adapter implementations
• Verify contracts work end-to-end
• Cover all I/O adapters

Test Organization:

• Unit/Integration tests: Co-located with implementation
• E2E tests: Separate /e2e directory

Language-Specific Idioms

How to achieve testability in each ecosystem:

Enforcement Checklist

Before marking code complete, verify:

• Can I run unit tests without starting database/external services?
• Are all I/O operations behind an abstraction?
• Is business logic pure (no side effects)?
• Do integration tests exist for all adapters?
• Does pattern match existing codebase (80%+ consistency)?

Related Principles

• SOLID: Dependency Inversion - Ports as abstractions
• Testing: Mock Ports Strategy - Unit test isolation
• Code Organization: Feature Packaging - Vertical slices
• Dependency Management: Avoid Circular - Layer separation

Core Design Principles

SOLID Principles

Single Responsibility Principle (SRP):

• Each class, module, or function should have ONE and ONLY ONE reason to change
• Generate focused, cohesive units of functionality
• If explaining what something does requires "and", it likely violates SRP

Open/Closed Principle (OCP):

• Software entities should be open for extension but closed for modification
• Design abstractions (interfaces, ports) that allow behavior changes without modifying existing code
• Use composition and dependency injection to enable extensibility

Liskov Substitution Principle (LSP):

• Subtypes must be substitutable for their base types without altering program correctness
• Inheritance hierarchies must maintain behavioral consistency
• If substituting a subclass breaks functionality, LSP is violated

Interface Segregation Principle (ISP):

• Clients should not be forced to depend on interfaces they don't use
• Create focused, role-specific interfaces rather than monolithic ones
• Many small, cohesive interfaces > one large, general-purpose interface

Dependency Inversion Principle (DIP):

• Depend on abstractions (interfaces/ports), not concretions (implementations/adapters)
• High-level modules should not depend on low-level modules; both should depend on abstractions
• Core principle enabling Testability-First architecture

Essential Design Practices

DRY (Don't Repeat Yourself):

• Eliminate code duplication through proper abstraction, shared utilities, composable functions
• Each piece of knowledge should have single, authoritative representation
• Don't duplicate logic, algorithms, or business rules

YAGNI (You Aren't Gonna Need It):

CRITICAL: Code maintainability always prevail

• Avoid implementing functionality before it's actually required
• Don't add features based on speculation about future needs
• Build for today's requirements, refactor when needs change

KISS (Keep It Simple, Stupid):

CRITICAL: Code maintainability always prevail

• Prefer simple(simple to maintain), straightforward solutions over complex, clever ones
• Complexity should be justified by actual requirements, not theoretical flexibility
• Simple code is easier to test, maintain, and debug

Separation of Concerns:

• Divide program functionality into distinct sections with minimal overlap
• Each concern should be isolated in its own module or layer

Composition Over Inheritance:

• Favor object composition and delegation over class inheritance for code reuse
• Composition is more flexible and easier to test
• Use interfaces/traits for polymorphism instead of deep inheritance hierarchies

Principle of Least Astonishment:

• Code should behave in ways that users and maintainers naturally expect
• Avoid surprising or counterintuitive behavior
• Follow established conventions and patterns

Code Organization Principles

• Generate small, focused functions with clear single purposes (typically 10-50 lines)
• Keep cognitive complexity low (cyclomatic complexity < 10 for most functions)
• Maintain clear boundaries between different layers (presentation, business logic, data access)
• Design for testability from the start, avoiding tight coupling that prevents testing
• Apply consistent naming conventions that reveal intent without requiring comments

Error Handling Principles

Error Categories

1. Validation Errors (4xx):

• User input doesn't meet requirements (wrong format, missing fields, out of range)
• Examples: Invalid email, password too short, required field missing
• Response: 400 Bad Request with detailed field-level errors
• User can fix: Yes, by correcting input

2. Business Errors (4xx):

• Domain rule violations (insufficient balance, duplicate email, order already shipped)
• Examples: Can't delete user with active orders, can't process refund after 30 days
• Response: 400/409/422 with business rule explanation
• User can fix: Maybe, depends on business context

3. Authentication Errors (401):

• Identity verification failed (invalid credentials, expired token, missing token)
• Response: 401 Unauthorized
• User can fix: Yes, by providing valid credentials

4. Authorization Errors (403):

• Permission denied (user identified but lacks permission)
• Response: 403 Forbidden
• User can fix: No, requires admin intervention

5. Not Found Errors (404):

• Resource doesn't exist or user lacks permission to know it exists
• Response: 404 Not Found
• User can fix: No

6. Infrastructure Errors (5xx):

• Database down, network timeout, external service failure, out of memory
• Response: 500/502/503 with generic message
• User can fix: No, system issue

Recoverable vs Non-Recoverable Errors

Recoverable (4xx - User can fix):

• Invalid input, missing fields, wrong format
• Action: Allow retry with corrected input
• Response: Detailed error message with guidance

Non-Recoverable (5xx - System issue):

• Database down, disk full, out of memory
• Action: Log details, alert ops team, return safe generic error
• Response: Generic message, correlation ID for support

Universal Error Handling Principles

1. Never Fail Silently:

• All errors must be handled explicitly (no empty catch blocks)
• If you catch an error, do something with it (log, return, transform, retry)

2. Fail Fast:

• Detect and report errors as early as possible
• Validate at system boundaries before processing
• Don't process invalid data hoping it'll work out

3. Provide Context:

• Include error codes, correlation IDs, actionable messages
• Enough information for debugging without exposing sensitive details
• Example: "Database query failed (correlation-id: abc-123)" not "SELECT * FROM users WHERE..."

4. Separate Concerns:

• Different handlers for different error types
• Business errors ≠ technical errors ≠ security errors

5. Resource Cleanup:

• Always clean up in error scenarios (close files, release connections, unlock resources)
• Use language-appropriate patterns (defer, finally, RAII, context managers)

6. No Information Leakage:

• Sanitize error messages for external consumption
• Don't expose stack traces, SQL queries, file paths, internal structure to users
• Log full details internally, show generic message externally

Application Error Object (Internal/Log Format)

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "User-friendly error message",
  "correlationId": "uuid-for-tracking",
  "details": {
    "field": "email",
    "issue": "Invalid email format",
    "provided": "invalid-email",
    "expected": "valid email format (user@example.com)"
  }
}

Error Handling Checklist

• Are all error paths explicitly handled (no empty catch blocks)?
• Do errors include correlation IDs for debugging?
• Are sensitive details sanitized before returning to client?
• Are resources cleaned up in all error scenarios?
• Are errors logged at appropriate levels (warn for 4xx, error for 5xx)?
• Are error tests written (negative test cases)?
• Is error handling consistent across application?

Related Principles

• API Design: Error Response Format - JSON envelope structure
• Logging: Correlation IDs - Traceability
• Security: No Information Leakage - Sanitization
• Testing: Negative Test Cases - Error path coverage
• Concurrency: Error in Thread Context - Thread failures

Concurrency and Threading Principles

When to Use Concurrency

I/O-Bound Operations (async/await, event loops):

• Network requests, file I/O, database queries
• Waiting for external responses dominates execution time
• Use: Asynchronous I/O, event-driven concurrency, coroutines

CPU-Bound Operations (threads, parallel processing):

• Heavy computation, data processing, video encoding
• CPU cycles dominate execution time
• Use: OS threads, thread pools, parallel workers

Don't Over-Use Concurrency:

• Adds significant complexity (race conditions, deadlocks, debugging difficulty)
• Use only when there's measurable performance benefit
• Profile first, optimize second

Universal Concurrency Principles

1. Avoid Race Conditions

What is a race condition:

• Multiple threads access shared data concurrently
• At least one thread writes/modifies the data
• No synchronization mechanism in place
• Result depends on unpredictable thread execution timing

Prevention strategies:

• Synchronization: Locks, mutexes, semaphores
• Immutability: Immutable data is thread-safe by default
• Message passing: Send data between threads instead of sharing
• Thread-local storage: Each thread has its own copy

Detection:

• Go: Run with -race flag (race detector)
• Rust: Miri tool for undefined behavior detection
• C/C++: ThreadSanitizer (TSan)
• Java: JCStress, FindBugs

2. Prevent Deadlocks

What is a deadlock:

• Two or more threads waiting for each other indefinitely
• Example: Thread A holds Lock 1, waits for Lock 2; Thread B holds Lock 2, waits for Lock 1

Four conditions (ALL must be true for deadlock):

1. Mutual exclusion: Resources held exclusively (locks)
2. Hold and wait: Holding one resource while waiting for another
3. No preemption: Can't force unlock
4. Circular wait: A waits for B, B waits for A

Prevention (break any one condition):

• Lock ordering: Always acquire locks in same order
• Timeout: Use try_lock with timeout, back off and retry
• Avoid nested locks: Don't hold multiple locks simultaneously
• Use lock-free data structures when possible

3. Prefer Immutability

• Immutable data = thread-safe by default (no synchronization needed)
• Share immutable data freely between threads
• Use immutable data structures where possible (Rust default, functional languages)
• If data must change, use message passing instead of shared mutable state

4. Message Passing Over Shared Memory

• "Don't communicate by sharing memory; share memory by communicating" (Go proverb)
• Send data through channels/queues instead of accessing shared memory
• Reduces need for locks and synchronization
• Easier to reason about and test

5. Graceful Degradation

• Handle concurrency errors gracefully (timeouts, retries, circuit breakers)
• Don't crash entire application on one thread failure
• Use supervisors/monitors for fault tolerance (Erlang/Elixir actor model)
• Implement backpressure for producer-consumer scenarios

Concurrency Models by Use Case

• I/O-bound: async/await, event loops, coroutines, green threads
• CPU-bound: OS threads, thread pools, parallel processing
• Actor model: Erlang/Elixir actors, Akka (message passing, isolated state)
• CSP (Communicating Sequential Processes): Go channels, Rust channels

Testing Concurrent Code

• Write unit tests with controlled concurrency (deterministic execution)
• Test timeout scenarios and resource exhaustion
• Test thread pool full, queue full scenarios

Related Principles

• Resource and Memory Management Principles
• Error Handling Principles
• Testing Strategy

Resource and Memory Management Principles

Universal Resource Management Rules

1. Always Clean Up Resources

Resources requiring cleanup:

• Files, network connections, database connections
• Locks, semaphores, mutexes
• Memory allocations (in manual-memory languages)
• OS handles, GPU resources

Clean up in ALL paths:

• Success path: Normal completion
• Error path: Exception thrown, error returned
• Early return path: Guard clauses, validation failures

Use language-appropriate patterns:

• Go: defer statements
• Rust: Drop trait (RAII)
• Python: context managers (with statement)
• TypeScript: try/finally
• Java: try-with-resources

2. Timeout All I/O Operations

Why timeout:

• Network requests can hang indefinitely
• Prevents resource exhaustion (connections, threads)
• Provides predictable failure behavior

Timeout recommendations:

• Network requests: 30s default, shorter (5-10s) for interactive
• Database queries: 10s default, configure per query complexity
• File operations: Usually fast, but timeout on network filesystems
• Message queue operations: Configurable, avoid indefinite blocking

3. Pool Expensive Resources

Resources to pool:

• Database connections: Pool size 5-20 per app instance
• HTTP connections: Reuse with keep-alive
• Thread pools: Size based on CPU count (CPU-bound) or I/O wait (I/O-bound)

Benefits:

• Reduces latency (no connection setup overhead)
• Limits resource consumption (cap on max connections)
• Improves throughput (reuse vs create new)

Connection Pool Best Practices:

• Minimum connections: 5 (ensures pool is warm)
• Maximum connections: 20-50 (prevents overwhelming database)
• Idle timeout: Close connections idle >5-10 minutes
• Validation: Test connections before use (avoid broken connections)
• Monitoring: Track utilization, wait times, timeout rates

4. Avoid Resource Leaks

What is a leak:

• Acquire resource (open file, allocate memory, get connection)
• Never release it (forget to close, exception prevents cleanup)
• Eventually exhaust system resources (OOM, max connections, file descriptors)

Detection:

• Monitor open file descriptors, connection counts, memory usage over time
• Run long-duration tests, verify resource counts stay stable
• Use leak detection tools (valgrind, ASan, heap profilers)

Prevention:

• Use language patterns that guarantee cleanup (RAII, defer, context managers)
• Never rely on manual cleanup alone (use language features)

5. Handle Backpressure

Problem: Producer faster than consumer

• Queue grows unbounded → memory exhaustion
• System becomes unresponsive under load

Solutions:

• Bounded queues: Fixed size, block or reject when full
• Rate limiting: Limit incoming request rate
• Flow control: Consumer signals producer to slow down
• Circuit breakers: Stop accepting requests when overwhelmed
• Drop/reject: Fail fast when overloaded (better than crashing)

Memory Management by Language Type

Garbage Collected (Go, Java, Python, JavaScript, C#):

• Memory automatically freed by GC
• Still must release non-memory resources (files, connections, locks)
• Be aware of GC pauses in latency-sensitive applications
• Profile memory usage to find leaks (retained references preventing GC)

Manual Memory Management (C, C++):

• Explicit malloc/free or new/delete
• Use RAII pattern in C++ (Resource Acquisition Is Initialization)
• Avoid manual management in modern C++ (use smart pointers: unique_ptr, shared_ptr)

Ownership-Based (Rust):

• Compiler enforces memory safety at compile time
• No GC pauses, no manual management
• Ownership rules prevent leaks and use-after-free automatically
• Use reference counting (Arc, Rc) for shared ownership

Related Principles

• Concurrency and Threading Principles - Thread safety, timeouts
• Error Handling Principles - Resource cleanup in error paths

API Design Principles

RESTful API Standards

Resource-Based URLs:

• Use plural nouns for resources: /api/{version}/users, /api/{version}/orders
• Hierarchical relationships: /api/{version}/users/:userId/orders
• Avoid verbs in URLs: /api/{version}/getUser ❌ → /api/{version}/users/:id ✅

HTTP Methods:

• GET: Read/retrieve resource (safe, idempotent, cacheable)
• POST: Create new resource (not idempotent)
• PUT: Replace entire resource (idempotent)
• PATCH: Partial update (idempotent)
• DELETE: Remove resource (idempotent)

HTTP Status Codes:

• 200 OK: Success (GET, PUT, PATCH)
• 201 Created: Resource created successfully (POST)
• 204 No Content: Success with no response body (DELETE)
• 400 Bad Request: Invalid input, validation failure
• 401 Unauthorized: Authentication required or failed

…(truncated)