Skip to main content

ADR-004: API Architecture (v4) - Part 1: Narrative & Visual

Status: Implemented
Date: 2025-08-27
Context: CODITECT API Architecture Decision

Purpose of this ADR​

This Architecture Decision Record serves two critical purposes:

  1. For Humans: Documents the "why" behind our API design choices, providing context and rationale that helps teams understand and extend the system.

  2. For AI Agents: Provides the complete blueprint (code, tests, configurations) needed for autonomous implementation by AI agents in the CODITECT platform.

Executive Summary (For Everyone)​

Imagine CODITECT's API as the reception desk of a massive, automated office building:

  • Visitors (users/apps) arrive and identify themselves with a badge (JWT token)
  • Security checks their credentials and assigns them a floor (tenant isolation)
  • Receptionists (API handlers) direct them to the right department (services)
  • Department staff (repositories) fetch requested information from filing cabinets (FoundationDB)

For technical readers: We chose Actix-web for its actor-based concurrency model, achieving sub-millisecond response times at scale while maintaining strict multi-tenant isolation.

Visual Architecture Overview​

Why These Technologies? (Dual Perspective)​

For Business Stakeholders​

  • Actix-web: Think of it as hiring Olympic athletes to handle requests - they're fast, efficient, and can handle many tasks simultaneously
  • JWT Tokens: Like secure, self-expiring visitor badges that can't be forged
  • Cloud Run: Automatically adds more receptionists when busy, removes them when quiet (cost-efficient)
  • FoundationDB: A filing system that never loses data and can handle millions of files

For Engineers​

  • Actix-web: Actor-model concurrency, zero-cost abstractions, 1M+ RPS capability
  • JWT (RS256): Stateless auth, distributed verification, claims-based authorization
  • Cloud Run: Container-as-a-Service, 0-100 scale, sub-second cold starts
  • FoundationDB: ACID transactions, multi-version concurrency control, automatic sharding

Request Flow Visualization​

API Request Lifecycle

Client HTTPS Cloud Run Middleware Pipeline 
<rect x="10" y="35" width="180" height="35" fill="#FFB84D" rx="3"/>
<text x="100" y="57" text-anchor="middle">1. CORS Check</text>

<rect x="10" y="75" width="180" height="35" fill="#FF6B6B" rx="3"/>
<text x="100" y="97" text-anchor="middle">2. JWT Validation</text>

<rect x="10" y="115" width="180" height="35" fill="#4ECDC4" rx="3"/>
<text x="100" y="137" text-anchor="middle">3. Rate Limiting</text>

<rect x="10" y="155" width="180" height="35" fill="#95E1D3" rx="3"/>
<text x="100" y="177" text-anchor="middle">4. Audit Logging</text>
 Business Logic Handler → Service → Repository FoundationDB Response

API Endpoint Organization (113 Total)​

Our API is organized into logical resource groups, following RESTful principles:

Security Architecture​

For Non-Technical Readers​

Think of our security like a high-security building:

  1. Entry Badge (JWT): Expires every hour, preventing stolen badges from working long
  2. Floor Access (Tenant Isolation): Can only access your company's floor
  3. Security Cameras (Audit Logs): Every action is recorded
  4. Visitor Limits (Rate Limiting): Prevents someone from overwhelming the reception

For Technical Readers​

Security Layers

Network Security HTTPS, TLS 1.3, HSTS Headers Authentication JWT RS256, Refresh Tokens, MFA (planned) Authorization Tenant Isolation, RBAC (planned) Application Security Input Validation, CORS, Rate Limiting Data

Performance Characteristics​

Real-World Analogy​

Our API performs like a Formula 1 pit crew:

  • Response Time: 50ms average (faster than a blink of an eye)
  • Throughput: 10,000 requests/second per instance
  • Scaling: 0 to 100 instances in under 10 seconds

Technical Metrics​

  • p50 Latency: 50ms
  • p95 Latency: 200ms
  • p99 Latency: 500ms
  • Max RPS: 1M+ (100 instances)
  • Cold Start: <1s
  • Memory: 512MB per instance
  • CPU: 1 vCPU per instance

Multi-Tenant Architecture​

Summary​

The CODITECT API is engineered for:

  • Developers: Clean REST interface, comprehensive docs, predictable behavior
  • Operations: Auto-scaling, detailed monitoring, zero-downtime deployments
  • Business: Cost-efficient, secure, compliant with regulations
  • AI Agents: Self-describing endpoints, structured responses, idempotent operations

Next: See Part 2: Technical Implementation for code examples, implementation details, and testing strategies.