8. Chapter review

The multi-source architecture serves several purposes at once. Pedagogically, it demonstrates handling different authentication patterns in one system (an API key in a header, an API key in a query string, and OAuth 2.0). This is crucial learning because production systems rarely have the luxury of uniform interfaces, you integrate whatever data sources provide value. Practically, using multiple sources increases article availability within free tier limits (100/day NewsAPI + 500/day Guardian + 60/min Reddit = much more content). From a product perspective, diversity matters: The Guardian provides high-quality journalism with editorial standards, NewsAPI aggregates from thousands of sources with algorithmic ranking, and Reddit offers community-driven news with discussion. The combination creates a more comprehensive news intelligence platform than any single source could provide. This architectural pattern, integrating multiple heterogeneous sources behind a unified interface, is exactly what professional APIs do.

The cache returns the 10:00 AM results immediately (~5ms response): the cache-aside path is: first request at 10:00 AM, application checks Redis, misses, fans out to all three external APIs in parallel (~800ms), writes the merged result set into Redis with a 5-minute TTL, and returns the response. The TTL countdown starts at 10:00 AM, so the key expires at 10:05 AM. On the second request at 10:03 AM the application checks Redis, the key is still live, and the application returns the cached value in roughly 5ms -- two orders of magnitude faster than the miss path. The TTL is fixed, not sliding: accessing a cached value does not reset the expiry, so the key disappears at 10:05 AM regardless of how many reads hit it in between. Sliding expiration is an option some caches expose, but a fixed TTL is simpler to reason about and predictable for news content where staleness is bounded by the policy, not by access patterns.

The CloudWatch alarm hasn't been in ALARM state long enough: Auto-scaling isn't instantaneous. CloudWatch alarms require multiple datapoints above the threshold before transitioning to ALARM state. For example, if your alarm requires 2 datapoints out of 2 evaluation periods with 1-minute intervals, CPU must exceed 70% for 2 consecutive minutes before the alarm triggers. This prevents scaling on brief spikes, a 10-second burst to 75% CPU followed by return to 50% shouldn't launch containers. Once the alarm enters ALARM state, ECS receives the scaling action, which then takes 2-4 minutes to launch new containers (pull image, start task, pass health checks, register with ALB). Total time from "CPU exceeds threshold" to "new container serving traffic" is typically 3-6 minutes. Health check failures prevent containers from receiving traffic but don't prevent launching. The maximum is 10 containers and you're only running 2, so that's not the limit. Cooldown periods exist but are typically 60-300 seconds, and wouldn't prevent the initial scale-out. The most common cause of "scaling didn't happen when I expected" is: not understanding alarm evaluation periods. Production systems must tolerate 3-6 minute scaling lag, which is why you run minimum capacity to handle baseline traffic without auto-scaling.

Several distinct problems all surface as the same 401, which is what makes OAuth failures so hard to debug. OAuth debugging is frustrating because authorization servers return generic 401 errors for many distinct problems. Authorization codes are single-use and expire in 60 seconds, if your code tries to exchange the same code twice (perhaps because of a retry or double-click), the second attempt gets 401. The redirect_uri must match EXACTLY between authorization and token requests, "http://localhost:8000/callback" ≠ "http://localhost:8000/callback/" (trailing slash). Reddit requires Basic auth with base64-encoded client_id:client_secret, malformed encoding or wrong credentials = 401. Other causes include: expired authorization codes (waited too long to exchange), wrong grant_type parameter, or clock skew between servers. The OAuth spec intentionally returns vague errors to prevent information leakage to attackers. Your debugging strategy: (1) Log the complete authorization URL and verify redirect_uri exactly, (2) Test client_id:client_secret auth separately, (3) Exchange codes immediately (don't wait), (4) Never reuse codes. The implementation in Section 3 handles these patterns correctly, but OAuth failures will still happen, expect to spend 1-2 hours debugging OAuth when you first implement it.

Production debugging means systematically checking multiple failure points. Production deployment failures require systematic investigation across multiple layers. Start with CloudWatch Logs (ECS -> Task -> Logs tab in AWS Console). Containers write stdout/stderr to CloudWatch, so you'll see FastAPI startup logs, database connection errors, or Python exceptions. Common causes: Missing environment variables (DATABASE_URL incorrect or not set), wrong database credentials, incorrect Redis host/port, or application crashes on startup. Next check security groups: if your container can't reach RDS (port 5432) or ElastiCache (port 6379), the application fails health checks even though it started. Verify: ECS security group has outbound rules, RDS/ElastiCache security groups allow inbound from ECS security group. Health check configuration matters too: if your ALB health check path is /health but your application only exposes /healthz, health checks always fail. Debugging strategy: (1) CloudWatch Logs first (application-level errors), (2) Security groups second (network-level errors), (3) Environment variables third (configuration errors), (4) Health check config fourth (monitoring errors). Chapter 29 covers operations, production debugging is a core competency. Tests pass locally but fail in production? Environment differences. Containers fail immediately? Check logs. Containers start but fail health checks? Network or health check config.

When storing in the database, analyze once per article and store results: Sentiment analysis should happen when articles are first stored in PostgreSQL (the write path) rather than when fetching from external APIs or on-demand when users request data. Here's why: analyzing on the write path means you compute sentiment once per article, store the result in the database, and every subsequent read is fast (just query the database). If you analyzed on-demand, users would wait for TextBlob to process article text on every view, slow and wasteful. If you analyzed when fetching from external APIs, you'd need to analyze the same article multiple times when different users search similar queries, and cached results would include sentiment but cache invalidation becomes complex. Background jobs add latency, articles fetched at 10:00 AM don't get sentiment until the 11:00 AM batch job runs. The write-path approach means: (1) User searches "climate change", (2) Your API fetches from external APIs, (3) For each new article, run sentiment analysis and store in article_sentiments table, (4) Return articles with sentiment data, (5) Next user searching "climate change" gets cached results with sentiment already computed. This pattern, expensive operations on write, fast operations on read, is fundamental to system design. Reads happen more frequently than writes, so optimize the read path. Section 5's implementation correctly analyzes on database insert.

The architecture diagram plus the short rationale paragraphs underneath it. The README has several sections that matter (quick start, API surface, deployment, performance numbers), but the architecture diagram is the section that lets a reader who has never seen the project locate every component named anywhere else in the document. A picture of the six-component layout from §2 plus three or four "why this, not that" sentences ("PostgreSQL over MongoDB because the relationships are first-class and the full-text index goes in the same place as the data"; "Redis cache-aside in front of the upstream APIs because the upstream rate limits are tighter than the application's read volume") gives a reader the system's shape and its load-bearing decisions in one pass. The quick start gets them running; the API surface tells them what they can call; the architecture section is the one that's hardest to fake and the easiest to evaluate. The other sections matter -- a README that doesn't run from a fresh clone fails a different bar -- but the architecture diagram is the highest-information-density piece of the document.

Start by clarifying what "10x traffic" means, then identify the next bottleneck, then evaluate the cheapest option that resolves it. "10x" is ambiguous between read traffic (article searches) and write traffic (article ingestion) and the scaling story is different for each. If it's reads, the cache absorbs a lot of it; the next bottleneck is PostgreSQL connection capacity, and the cheapest fix is RDS read replicas with a routing rule in the application. If it's writes, the cache doesn't help; the next bottleneck is the upstream API rate limits plus PostgreSQL write throughput, and the cheapest fixes are batching the upstream pulls and partitioning the articles table by date. The deployed system already has ECS auto-scaling between 2 and 10 tasks, so the compute layer scales horizontally without any architectural change; that's the cheapest win and the one to verify first. The expensive options (a service mesh, microservices, Kubernetes) aren't warranted at 10x and aren't warranted by the actual bottleneck. The shape of the answer that lands is: identify which traffic, which bottleneck, which fix, and what you'd measure to confirm the fix worked. Numbers from the load test in §4 are the right reference point; vague claims aren't.