GKaszewski/thoughts
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add architecture diagram
Some checks failed
test / unit (push) Has been cancelled
Details
lint / lint (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Gabriel Kaszewski
2026-06-04 23:48:04 +02:00
parent 5a65fda0bc
commit 4d6df1ea60
1 changed files with 121 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
ARCHITECTURE.md Normal file
View File

@@ -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