docs: improve docs

README.md

@@ -70,19 +70,48 @@ Example response:
 
 `/pokemon/translated/{name}` applies Yoda when the Pokémon is legendary or its habitat is `cave`; otherwise it applies Shakespeare. If translation fails or returns an empty result, the API falls back to the standard PokéAPI description.
 
-## Architecture
+# Architecture
+
+This is a small Rust service, so the structure is intentionally a lightweight hexagonal/onion layout rather than a framework-heavy one.
 
 ```mermaid
 flowchart LR
-  CLI[CLI helper] --> HTTP[HTTP layer]
-  HTTP --> APP[Application service]
-  APP --> DOMAIN[Domain]
-  APP --> CLIENTS[External clients]
-  HTTP --> OTEL[Telemetry]
-  APP --> OTEL
+  CLI[CLI helper] --> HTTP
+  API[API binary] --> Config
+  API --> HTTP
+  Config[Configuration] --> HTTP
+  HTTP[HTTP layer: axum routes, handlers, middleware, app wiring] --> Application
+  Application[Application service: use cases and translation rules] --> Domain
+  Application --> Clients
+  Clients[External clients: PokéAPI and FunTranslations]
+  Clients --> Domain
+  HTTP --> Telemetry
+  Application --> Telemetry
+  Error[Shared errors] -.-> HTTP
+  Error -.-> Application
+  Error -.-> Clients
 ```
 
-See `docs/architecture.md` for the design notes.
+## Layers
+
+- `domain`: core data and business concepts (`PokemonInfo`, `TranslationKind`).
+- `application`: orchestration and business rules, including Yoda vs Shakespeare selection and fallback behavior.
+- `clients`: adapters for external providers (`PokéAPI`, `FunTranslations`).
+- `http`: API transport concerns, routing, handlers, request IDs, metrics middleware, and rate limiting.
+- `telemetry`: OpenTelemetry metrics and tracing setup.
+- `config`: environment-backed application configuration.
+- `error`: shared application and API error types.
+- `bin`: executable entrypoints for the API and the local CLI helper.
+
+`http::AppState::from_config` is also where this small service wires concrete clients, telemetry, rate limiting and the application service together. Request handling then follows the simpler path `http -> application -> clients`, with `domain`, `error` and `telemetry` shared across those layers.
+
+## Deliberate trade-offs
+
+The application service currently depends on concrete clients instead of trait-based ports. For this challenge that keeps the code easier to read and avoids abstractions that do not buy much yet. In a larger enterprise codebase, those clients would likely become traits owned by the application layer, with HTTP clients as adapters, so providers could be swapped or mocked without depending on concrete implementations.
+
+Rate limiting is intentionally simple and in-memory. In production, this should usually live in an API gateway or shared rate-limiting service so limits are consistent across instances and can be keyed by API key, user, or client IP. PokéAPI species data also changes rarely, so production deployments would add a bounded LRU cache with TTL for successful species responses to avoid unnecessary random upstream hits, reduce latency, and make transient provider failures less visible to users.
+
+External contract tests are separated from the normal deterministic test suite. Unit and integration tests use mocks; the nightly workflow calls real providers to detect contract drift early.
 
 ## Configuration
 
@@ -134,4 +163,4 @@ The Dockerfile uses `cargo-chef` and BuildKit cache mounts for dependency and ta
 
 ## Production notes
 
-For a production API I would add per-client or per-token rate limiting instead of one global bucket, retries with bounded exponential backoff, circuit breakers for upstream failures, and a bounded LRU/TTL cache for PokéAPI data. Species content changes rarely, so caching successful responses would avoid unnecessary random upstream hits, reduce latency, and make transient provider failures less visible to users. I would also add stronger health checks that distinguish readiness from liveness, dashboards and alerts from the OTEL metrics, and a dedicated OTEL collector pipeline. I would keep `/metrics` private, add dependency/container scanning, define SLOs, and add contract tests against recorded upstream fixtures.
+For a production API I would add retries with bounded exponential backoff, circuit breakers for upstream failures, stronger health checks that distinguish readiness from liveness, dashboards and alerts from the OTEL metrics, and a dedicated OTEL collector pipeline. I would keep `/metrics` private, add dependency/container scanning, define SLOs, and add contract tests against recorded upstream fixtures.

docs/architecture.md

@@ -1,33 +0,0 @@
-# Architecture
-
-This is a small Rust service, so the structure is intentionally a lightweight hexagonal/onion layout rather than a framework-heavy one.
-
-```mermaid
-flowchart LR
-  CLI[CLI helper] --> HTTP
-  HTTP[HTTP layer: axum routes, handlers, middleware] --> Application
-  Application[Application service: use cases and translation rules] --> Domain
-  Application --> Clients
-  Clients[External clients: PokéAPI and FunTranslations]
-  HTTP --> Telemetry
-  Application --> Telemetry
-```
-
-## Layers
-
-- `domain`: core data and business concepts (`PokemonInfo`, `TranslationKind`).
-- `application`: orchestration and business rules, including Yoda vs Shakespeare selection and fallback behavior.
-- `clients`: adapters for external providers (`PokéAPI`, `FunTranslations`).
-- `http`: API transport concerns, routing, handlers, request IDs, metrics middleware, and rate limiting.
-- `telemetry`: OpenTelemetry metrics and tracing setup.
-- `bin`: executable entrypoints for the API and the local CLI helper.
-
-## Deliberate trade-offs
-
-The application service currently depends on concrete clients instead of trait-based ports. For this challenge that keeps the code easier to read and avoids abstractions that do not buy much yet. In a larger enterprise codebase, those clients would likely become traits owned by the application layer, with HTTP clients as adapters, so providers could be swapped or mocked without depending on concrete implementations.
-
-PokéAPI species data changes rarely, so production deployments would add a bounded LRU cache with TTL for successful species responses. That would avoid unnecessary random upstream hits, reduce latency, and make transient provider failures less visible to users.
-
-Rate limiting is intentionally simple and in-memory. In production, this should usually live in an API gateway or shared rate-limiting service so limits are consistent across instances and can be keyed by API key, user, or client IP.
-
-External contract tests are separated from the normal deterministic test suite. Unit and integration tests use mocks; the nightly workflow calls real providers to detect contract drift early.