feat: document api contract

README.md

@@ -68,6 +68,20 @@ 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
+
+```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
+```
+
+See `docs/architecture.md` for the design notes.
+
 ## Configuration
 
 | Variable | Default | Description |