From 4d6df1ea6079c3f0bc7816cfc0ff45e5f7e51190 Mon Sep 17 00:00:00 2001 From: Gabriel Kaszewski Date: Thu, 4 Jun 2026 23:48:04 +0200 Subject: [PATCH] docs: add architecture diagram --- ARCHITECTURE.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..de8ba61 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,121 @@ +# Architecture + +Hexagonal (ports & adapters) architecture. Dependencies point inward — adapters implement domain ports, application orchestrates use cases, presentation handles HTTP. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ ENTRY POINTS │ +│ │ +│ ┌─────────────┐ ┌──────────┐ │ +│ │ bootstrap │ │ worker │ │ +│ │ (HTTP srv) │ │ (bg jobs) │ │ +│ └──────┬───────┘ └─────┬─────┘ │ +│ │ wires all deps │ consumes events │ +└─────────┼────────────────────────┼──────────────────────────────────────┘ + │ │ + ▼ ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ INTERFACE LAYER │ +│ │ +│ ┌──────────────────┐ ┌────────────┐ │ +│ │ presentation │ │ api-types │ │ +│ │ (axum handlers, │◄───│ (DTOs, │ │ +│ │ extractors, │ │ OpenAPI) │ │ +│ │ AppState) │ └────────────┘ │ +│ └────────┬──────────┘ │ +│ │ calls use cases │ +└───────────┼─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ APPLICATION LAYER │ +│ │ +│ ┌─────────────────────────────────────────────┐ │ +│ │ application │ │ +│ │ │ │ +│ │ use_cases/ │ │ +│ │ thoughts, social, profile, │ │ +│ │ federation_management │ │ +│ │ │ │ +│ │ services/ │ │ +│ │ FederationEventService │ │ +│ │ (processes domain events → broadcasts) │ │ +│ └──────────────────┬──────────────────────────┘ │ +│ │ depends only on domain ports │ +└─────────────────────┼───────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ DOMAIN LAYER (core) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ domain │ │ +│ │ │ │ +│ │ models/ value_objects/ events/ errors/ │ │ +│ │ Thought UserId DomainEvent DomainErr │ │ +│ │ User ThoughtId EventEnvelope │ │ +│ │ RemoteActor Username │ │ +│ │ Follow,Like Content │ │ +│ │ Boost,Block Email │ │ +│ │ Notification PasswordHash │ │ +│ │ Tag,FeedEntry │ │ +│ │ │ │ +│ │ ports/ (trait interfaces) │ │ +│ │ UserRepository FederationContentRepository │ │ +│ │ ThoughtRepository FederationBroadcastPort │ │ +│ │ LikeRepository FederationLookupPort │ │ +│ │ BoostRepository FederationFollowPort │ │ +│ │ FollowRepository FederationFollowRequestPort │ │ +│ │ BlockRepository FederationFetchPort │ │ +│ │ TagRepository FederationBlockPort │ │ +│ │ NotificationRepository FederationSchedulerPort │ │ +│ │ FeedRepository FederationActionPort (supertrait) │ │ +│ │ SearchPort EventPublisher / EventConsumer │ │ +│ │ AuthService MediaStore / OutboxWriter │ │ +│ │ PasswordHasher RemoteActorConnectionRepository │ │ +│ │ ApiKeyRepository EngagementRepository │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + ▲ + │ implements ports + │ +┌─────────────────────────────────────────────────────────────────────────┐ +│ ADAPTER LAYER │ +│ │ +│ ┌──────────────────┐ ┌─────────────────────┐ ┌──────────────────┐ │ +│ │ postgres │ │ activitypub │ │ auth │ │ +│ │ │ │ │ │ │ │ +│ │ UserRepository │ │ FederationActionPort│ │ AuthService │ │ +│ │ ThoughtRepo │ │ FederationBroadcast │ │ ApiKeyService │ │ +│ │ LikeRepo │ │ FederationContent.. │ └──────────────────┘ │ +│ │ BoostRepo │ │ FederationScheduler │ │ +│ │ FollowRepo │ │ │ ┌──────────────────┐ │ +│ │ BlockRepo │ │ (wraps k-ap lib) │ │ storage │ │ +│ │ TagRepo │ └─────────────────────┘ │ MediaStore │ │ +│ │ NotificationRepo │ └──────────────────┘ │ +│ │ ApiKeyRepo │ ┌─────────────────────┐ │ +│ │ TopFriendRepo │ │ postgres-federation │ ┌──────────────────┐ │ +│ │ FeedRepo │ │ (k-ap DB traits) │ │ nats │ │ +│ │ EngagementRepo │ └─────────────────────┘ │ EventPublisher │ │ +│ │ FederationContent│ │ EventConsumer │ │ +│ │ OutboxWriter │ ┌─────────────────────┐ └──────────────────┘ │ +│ │ RemoteActorRepo │ │ postgres-search │ │ +│ │ RemoteActorConn │ │ SearchPort │ ┌──────────────────┐ │ +│ └──────────────────┘ └─────────────────────┘ │ event-transport │ │ +│ │ event-payload │ │ +│ │ (serialization) │ │ +│ └──────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +## Dependency rule + +``` +bootstrap/worker ──► presentation ──► application ──► domain ◄── adapters +``` + +- **domain** — zero framework deps, pure business logic, defines all port traits +- **application** — orchestrates use cases, depends only on domain +- **presentation** — HTTP handlers (axum), depends on domain + application +- **adapters** — implement domain ports, depend inward on domain only +- **bootstrap/worker** — composition roots, wire adapters into ports