diff --git a/architecture.mmd b/architecture.mmd
new file mode 100644
index 0000000..0f838dc
--- /dev/null
+++ b/architecture.mmd
@@ -0,0 +1,132 @@
+---
+title: Movies Diary — Hexagonal Architecture
+---
+graph TB
+    subgraph Binaries["Binaries (Composition Root)"]
+        WEB["presentation<br/><i>Axum web server</i><br/>Routes, Handlers, Mappers"]
+        WORKER["worker<br/><i>Event consumer</i><br/>Concurrent dispatch, graceful shutdown"]
+        TUI["tui<br/><i>Terminal UI</i>"]
+    end
+
+    subgraph Application["Application Layer"]
+        direction TB
+        CTX["AppContext<br/><i>Repositories + Services</i>"]
+        subgraph UseCases["Use Cases"]
+            UC_AUTH["auth<br/>login, register"]
+            UC_DIARY["diary<br/>log_review, get_diary,<br/>get_activity_feed, export"]
+            UC_MOVIES["movies<br/>get_movies, get_movie_profile,<br/>enrich_movie, sync_poster,<br/>reindex_search"]
+            UC_IMPORT["import<br/>create_session, apply_mapping,<br/>execute, profiles"]
+            UC_USERS["users<br/>get_users, get_profile,<br/>update_profile"]
+            UC_WATCHLIST["watchlist<br/>add, remove, get"]
+            UC_WRAPUP["wrapup<br/>generate, compute,<br/>list, delete"]
+            UC_INTEGRATIONS["integrations<br/>webhooks, watch_queue,<br/>confirm, dismiss"]
+            UC_SEARCH["search<br/>execute"]
+            UC_PERSON["person<br/>get, get_credits"]
+        end
+        subgraph EventHandlers["Event Handlers"]
+            EH_ENRICH["EnrichmentHandler"]
+            EH_DISCOVER["MovieDiscoveryIndexer"]
+            EH_CLEANUP["SearchCleanupHandler"]
+            EH_REINDEX["SearchReindexHandler"]
+            EH_WRAPUP["WrapUpEventHandler"]
+        end
+        subgraph Jobs["Periodic Jobs"]
+            JOB_IMPORT["ImportSessionCleanup"]
+            JOB_WATCH["WatchEventCleanup"]
+            JOB_STALE["EnrichmentStaleness"]
+            JOB_WRAPGEN["WrapUpAutoGenerate"]
+        end
+        WORKER_SVC["WorkerService<br/><i>Semaphore(8), JoinSet,<br/>shutdown signal</i>"]
+    end
+
+    subgraph Domain["Domain Layer (0 dependencies)"]
+        direction TB
+        subgraph Models["Models"]
+            M_MOVIE["Movie, MovieSummary,<br/>MovieProfile"]
+            M_REVIEW["Review, DiaryEntry,<br/>FeedEntry"]
+            M_USER["User, UserSummary"]
+            M_PERSON["Person, PersonId,<br/>PersonCredits"]
+            M_WATCHLIST["WatchlistEntry,<br/>WatchEvent"]
+            M_WRAPUP["WrapUpReport,<br/>MovieRef, PersonStat"]
+            M_SEARCH["SearchQuery,<br/>SearchResults"]
+        end
+        subgraph Ports["Port Traits (Interfaces)"]
+            P_REPOS["MovieRepository<br/>ReviewRepository<br/>DiaryRepository<br/>UserRepository<br/>WatchlistRepository<br/>WatchEventRepository<br/>WebhookTokenRepository<br/>ImportSessionRepository<br/>MovieProfileRepository<br/>WrapUpRepository"]
+            P_SERVICES["AuthService<br/>MetadataClient<br/>PosterFetcherClient<br/>ObjectStorage<br/>EventPublisher<br/>EventConsumer<br/>PasswordHasher<br/>DiaryExporter<br/>DocumentParser"]
+            P_SEARCH["SearchPort<br/>SearchCommand<br/>PersonQuery<br/>PersonCommand"]
+            P_FEDERATION["SocialQueryPort<br/>LocalApContentQuery<br/>RemoteWatchlistRepository"]
+        end
+        EVENTS["DomainEvent enum<br/><i>ReviewLogged, MovieDiscovered,<br/>SearchReindexRequested, ...</i>"]
+        VO["Value Objects<br/><i>MovieId, UserId, Rating,<br/>Email, Username, ...</i>"]
+    end
+
+    subgraph ApiTypes["api-types (0 domain deps)"]
+        DTO["DTOs<br/><i>MovieDto, ReviewDto,<br/>FeedEntryDto, UserSummaryDto,<br/>CastMemberDto, ...</i>"]
+    end
+
+    subgraph Adapters["Adapters (implement Port Traits)"]
+        direction TB
+        subgraph Storage["Storage"]
+            A_SQLITE["sqlite<br/><i>SQLite repos</i>"]
+            A_PG["postgres<br/><i>PostgreSQL repos</i>"]
+            A_SQLITE_SEARCH["sqlite-search<br/><i>FTS5</i>"]
+            A_PG_SEARCH["postgres-search<br/><i>tsvector/GIN</i>"]
+            A_OBJ["object-storage<br/><i>S3 / filesystem</i>"]
+        end
+        subgraph Messaging["Messaging"]
+            A_NATS["nats<br/><i>JetStream / Core</i>"]
+            A_PG_QUEUE["postgres-event-queue<br/><i>Polling, dead-letter</i>"]
+            A_PAYLOAD["event-payload<br/><i>Serde (de)serialization</i>"]
+        end
+        subgraph External["External Services"]
+            A_METADATA["metadata<br/><i>TMDB search/details</i>"]
+            A_TMDB["tmdb-enrichment<br/><i>Credits, keywords, cast</i>"]
+            A_POSTER["poster-fetcher<br/><i>TMDB image download</i>"]
+            A_AUTH["auth<br/><i>JWT tokens</i>"]
+        end
+        subgraph Federation["Federation (feature-gated)"]
+            A_AP["activitypub<br/><i>k_ap library</i>"]
+            A_SQLITE_FED["sqlite-federation"]
+            A_PG_FED["postgres-federation"]
+        end
+        subgraph Media["Media Processing"]
+            A_IMG["image-converter<br/><i>AVIF/WebP</i>"]
+            A_POSTER_SYNC["poster-sync"]
+            A_WRAPUP_RENDER["wrapup-renderer<br/><i>ffmpeg video, slides</i>"]
+        end
+        subgraph Presentation["Presentation Helpers"]
+            A_TEMPLATE["template-askama<br/><i>HTML templates</i>"]
+            A_RSS["rss<br/><i>Feed generation</i>"]
+            A_EXPORT["export<br/><i>CSV/JSON diary</i>"]
+            A_IMPORT["importer<br/><i>CSV/JSON/XLSX parser</i>"]
+        end
+        subgraph Webhooks["Webhook Parsers"]
+            A_JELLYFIN["jellyfin"]
+            A_PLEX["plex"]
+        end
+    end
+
+    %% Dependency arrows
+    WEB -->|"uses"| Application
+    WEB -->|"maps to"| ApiTypes
+    WORKER -->|"uses"| Application
+
+    Application -->|"depends on"| Domain
+
+    Adapters -.->|"implements"| Ports
+
+    %% Key data flows
+    WEB ===|"HTTP"| DTO
+    WORKER ===|"Events"| EVENTS
+
+    classDef domain fill:#1a1a2e,stroke:#e94560,color:#fff
+    classDef app fill:#16213e,stroke:#0f3460,color:#fff
+    classDef adapter fill:#0f3460,stroke:#533483,color:#fff
+    classDef binary fill:#533483,stroke:#e94560,color:#fff
+    classDef api fill:#2a2a4a,stroke:#e94560,color:#fff
+
+    class Domain domain
+    class Application app
+    class Adapters adapter
+    class Binaries binary
+    class ApiTypes api