Radixura/rss-atom-backend
SHA256
1
0
Fork 0
Code Issues 39 Pull requests Projects Releases Packages Wiki Activity Actions

docs/architecture.md — Architektur-Dokumentation #31

New issue
Open
opened 2026-06-21 23:04:15 +02:00 by Radixura · 0 comments
Radixura commented 2026-06-21 23:04:15 +02:00
Owner
Copy link

Ziel

Dokumentiere die Software-Architektur: Komponenten, Datenflüsse, Schichten, Design-Entscheidungen und Trade-offs.

Beschreibung

Die Architecture-Doku richtet sich an Entwickler, die das Projekt verstehen oder erweitern wollen. Sie erklärt das WARUM, nicht nur das WAS.

Akzeptanzkriterien

  • Architektur-Übersicht (Text oder ASCII-Diagramm):

    HTTP Layer (Axum)
├── Auth Middleware (X-API-Key / Query-Token)
├── REST Handlers (feeds, posts, admin)
│   ├── Repository Layer (DB-Queries)
│   └── Feed Generator (RSS / Atom)
├── Cache Layer (DashMap)
└── Database Layer (SQLx → SQLite WAL)

  • Schichten-Beschreibung:

    • HTTP Layer: Axum-Router, Handler, Middleware
    • Auth Layer: API-Key-Validierung, Header/Query-Token-Extraktion
    • Service/Repository Layer: DB-nahe Funktionen, Transaktions-Logik
    • Feed Generation Layer: RSS + Atom XML-Builder
    • Cache Layer: In-Memory Feed-Cache mit DashMap
    • Database Layer: SQLite mit WAL-Mode, SQLx-Migrationen

  • Datenfluss-Diagramme (pro Haupt-Workflow):

    • POST /api/v1/posts (Schreib-Pfad):
      Auth → Validation → DB-Transaktion → Cache-Refresh (async)
    • GET /feeds/:slug/rss.xml (Lese-Pfad):
      Request → Cache-Lookup → Cache-Hit? → Return XML
      → Cache-Miss? → DB-Query → Gen XML → Cache → Return

  • Design-Entscheidungen mit Begründung:

    • Warum SQLite statt PostgreSQL? (Siehe Issue #1 Beschreibung: Single-File, kein DB-Server, WAL reicht)
    • Warum DashMap statt Redis? (Kein externer Service, kein Netzwerk-Overhead, ausreichend für Feed-Caching)
    • Warum SHA-256 statt bcrypt für API-Keys? (API-Keys sind high-entropy 32-Byte-Random, kein Passwort)
    • Warum kein JWT? (API-Keys sind einfacher, RSS-Reader können keine JWTs)
    • Warum separate RSS + Atom Caches? (Unterschiedliche XML-Formate, unabhängige Generierung)

  • Trade-offs:

    • Cache-Invalidierung ist explizit → bei Crash: Cache geht verloren, Warming füllt ihn neu
    • Private Feeds nicht gecached → langsamer, aber kein Datenleck-Risiko
    • Keine horizontale Skalierung → SQLite ist Single-Writer, aber für Feed-Publishing ausreichend

Technische Hinweise

  • ASCII-Diagramme oder Mermaid (GitHub/Forgejo unterstützen Mermaid in Markdown)
  • Kein UML — einfache Block-Diagramme reichen
  • Max 3-4 Seiten Markdown
## Ziel Dokumentiere die Software-Architektur: Komponenten, Datenflüsse, Schichten, Design-Entscheidungen und Trade-offs. ## Beschreibung Die Architecture-Doku richtet sich an Entwickler, die das Projekt verstehen oder erweitern wollen. Sie erklärt das WARUM, nicht nur das WAS. ## Akzeptanzkriterien - [ ] Architektur-Übersicht (Text oder ASCII-Diagramm): ``` HTTP Layer (Axum) ├── Auth Middleware (X-API-Key / Query-Token) ├── REST Handlers (feeds, posts, admin) │ ├── Repository Layer (DB-Queries) │ └── Feed Generator (RSS / Atom) ├── Cache Layer (DashMap) └── Database Layer (SQLx → SQLite WAL) ``` - [ ] Schichten-Beschreibung: - **HTTP Layer:** Axum-Router, Handler, Middleware - **Auth Layer:** API-Key-Validierung, Header/Query-Token-Extraktion - **Service/Repository Layer:** DB-nahe Funktionen, Transaktions-Logik - **Feed Generation Layer:** RSS + Atom XML-Builder - **Cache Layer:** In-Memory Feed-Cache mit DashMap - **Database Layer:** SQLite mit WAL-Mode, SQLx-Migrationen - [ ] Datenfluss-Diagramme (pro Haupt-Workflow): - **POST /api/v1/posts** (Schreib-Pfad): Auth → Validation → DB-Transaktion → Cache-Refresh (async) - **GET /feeds/:slug/rss.xml** (Lese-Pfad): Request → Cache-Lookup → Cache-Hit? → Return XML → Cache-Miss? → DB-Query → Gen XML → Cache → Return - [ ] Design-Entscheidungen mit Begründung: - Warum SQLite statt PostgreSQL? (Siehe Issue #1 Beschreibung: Single-File, kein DB-Server, WAL reicht) - Warum DashMap statt Redis? (Kein externer Service, kein Netzwerk-Overhead, ausreichend für Feed-Caching) - Warum SHA-256 statt bcrypt für API-Keys? (API-Keys sind high-entropy 32-Byte-Random, kein Passwort) - Warum kein JWT? (API-Keys sind einfacher, RSS-Reader können keine JWTs) - Warum separate RSS + Atom Caches? (Unterschiedliche XML-Formate, unabhängige Generierung) - [ ] Trade-offs: - Cache-Invalidierung ist explizit → bei Crash: Cache geht verloren, Warming füllt ihn neu - Private Feeds nicht gecached → langsamer, aber kein Datenleck-Risiko - Keine horizontale Skalierung → SQLite ist Single-Writer, aber für Feed-Publishing ausreichend ## Technische Hinweise - ASCII-Diagramme oder Mermaid (GitHub/Forgejo unterstützen Mermaid in Markdown) - Kein UML — einfache Block-Diagramme reichen - Max 3-4 Seiten Markdown
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Radixura/rss-atom-backend#31
No description provided.