Documentation

metadata:
  name: "URL Shortener"
  version: "1.0"
  author: "johndoe"
  description: "A scalable URL shortening service"

systems:
  api-gateway:
    type: container
    description: "NGINX reverse proxy"
  shortener-service:
    type: component
    description: "Core URL shortening logic"
    parent: api-gateway
  cache:
    type: container
    description: "Redis cache for hot URLs"

relationships:
  - from: api-gateway
    to: shortener-service
    type: sync-http
  - from: shortener-service
    to: cache
    type: async-pubsub

events:
  url_created:
    producer: shortener-service
    consumers: [analytics-service]
    payload: { url_id: string, original_url: string }

capacity:
  daily_active_users: 10_000_000
  read_qps: 100_000
  write_qps: 1_000
  storage_tb: 50

decisions:
  - id: ADR-001
    title: "Use Redis for caching"
    context: "Hot URL lookups dominate traffic"
    decision: "Redis cluster with read replicas"
    consequences: "Adds operational complexity but reduces DB load 90%"

nfrs:
  availability: "99.95%"
  latency_p99_ms: 50
  security: "HTTPS-only, API key auth"

project:
  name: "url_shortener"
  display_name: "URL Shortener Service"
  description: "A scalable URL shortening platform"
  owner: "platform-team"
  tags: ["web", "url-shortener"]

metadata:
  schema_version: "1.0"
  authors:
    - name: "Alice Wang"
      email: "alice@example.com"
      role: architect
  created_at: "2025-01-15"
  description: "System design for the ArchForge URL shortener challenge"

systems:
  - name: "API Gateway"
    description: "NGINX reverse proxy — entry point for all client traffic"
    containers:
      - name: "nginx"
        technology: "NGINX 1.25"
        type: gateway
        components:
          - name: "rate_limiter"
            technology: "Lua + Redis"
            type: handler
            responsibilities:
              - "Per-IP rate limiting"
              - "Request throttling"

  - name: "Shortener Service"
    description: "Core URL shortening logic"
    containers:
      - name: "api_server"
        technology: "FastAPI + Python 3.12"
        type: api_server
      - name: "postgres"
        technology: "PostgreSQL 16"
        type: database

relationships:
  - type: calls
    source: "API Gateway.nginx"
    target: "Shortener Service.api_server"
    protocol: https
    synchronous: true
    description: "Client requests proxied to shortener API"

  - type: reads_from
    source: "Shortener Service.api_server"
    target: "Shortener Service.postgres"
    protocol: jdbc
    synchronous: true

  - type: publishes_to
    source: "Shortener Service.api_server"
    target: "analytics_kafka.url_created_topic"
    protocol: tcp
    synchronous: false
    description: "Emit URL creation events to Kafka"

events:
  brokers:
    - name: "analytics_kafka"
      type: kafka
      version: "3.6"
      config:
        bootstrap_servers: "kafka:9092"

  topics:
    - name: "url_created_topic"
      broker: "analytics_kafka"
      type: topic
      partitions: 6
      replication_factor: 3
      retention: "7d"
      schema_format: avro
      producers:
        - "Shortener Service.api_server"
      consumers:
        - "Analytics Service.click_processor"

capacity:
  dau:
    estimated: 10000000
    peak_multiplier: 3.0
    growth_yoy_pct: 50
  qps:
    average: 5000
    peak: 15000
    per_endpoint:
      create_short_url: 2000
      redirect: 12000
  storage:
    per_record_bytes: 512
    records_per_day: 5000000
    retention_days: 365
    breakdown:
      urls_table:
        estimated_gb: 930
        storage_type: relational
  bandwidth:
    ingress_mbps: 25
    egress_mbps: 200
    peak_egress_mbps: 600

decisions:
  - id: "ADR-0001"
    title: "Use PostgreSQL for persistent storage"
    status: accepted
    date: "2025-01-15"
    context: "Need a durable store for URL mappings with strong consistency"
    decision: "PostgreSQL 16 with read replicas for scaling reads"
    options:
      - name: "PostgreSQL"
        pros: ["ACID compliance", "Strong consistency", "Mature ecosystem"]
        cons: ["Vertical scaling limits", "Replication lag on read replicas"]
        trade_off_dimensions:
          cost: medium
          complexity: low
          maturity: high
          scalability: medium
        risk_level: low
      - name: "MongoDB"
        pros: ["Schema flexibility", "Horizontal scaling"]
        cons: ["Eventual consistency by default", "Complex transactions"]
        trade_off_dimensions:
          cost: medium
          complexity: medium
          maturity: high
          scalability: high
        risk_level: medium
    consequences: "Strong consistency guarantees for URL mappings. Need connection pooling and read replica failover strategy."

nfrs:
  availability:
    target_pct: 99.95
    max_downtime_minutes_per_month: 21.9
    sla_description: "Three and a half nines"
  latency:
    p50_ms: 20
    p95_ms: 100
    p99_ms: 500
    per_endpoint:
      redirect:
        p50_ms: 5
        p95_ms: 20
        p99_ms: 50
  throughput:
    peak_qps: 15000
    sustained_qps: 5000
    burst_qps: 25000
  data_consistency: strong
  security:
    authentication: [oauth2, api_key]
    authorization_model: rbac
    data_classification: confidential
    encryption_at_rest: true
    encryption_in_transit: true
    compliance: [soc2, gdpr]