mitbringsl/docs/ARCHITECTURE.md

Mitbringsl – Architectural Design Document

1. Overview & Paradigm

Mitbringsl is a local-first, privacy-focused shopping list application designed as an ad-free alternative to Bring!.

Local-First Foundation

• Source of Truth: The client’s local SQLite database (via Room) is the authoritative source of truth for user interactions. All mutations (adding items, checking off items, renaming/deleting lists) take immediate effect locally.
• Append-Only Op Log: Operations are logged sequentially to a local outbox queue (op_log) before being synced asynchronously to the server.
• Offline Resiliency: The app functions 100% offline. Network connectivity is treated as an opportunistic transport to synchronize operations with the server and other clients.

---

2. System Architecture

                  ┌─────────────────────────────────────────┐
                  │              Caddy (Reverse Proxy)       │
                  └────────────────────┬────────────────────┘
                                       │ HTTP / REST
                  ┌────────────────────▼────────────────────┐
                  │        Go Backend (net/http + pgx)      │
                  └─────────┬──────────────────────┬────────┘
                            │                      │
                  ┌─────────▼────────┐   ┌─────────▼────────┐
                  │ PostgreSQL (16)  │   │  OIDC Providers  │
                  │ (op_log, LWW)    │   │  (Google/Custom) │
                  └──────────────────┘   └──────────────────┘

---

3. Technology Stack

Backend (Go 1.26)

• HTTP Routing: net/http stdlib (Go 1.22+ method & path variables pattern matching).
• Database Driver: github.com/jackc/pgx/v5 (pgxpool).
• Database Migrations: github.com/golang-migrate/migrate/v4 (embedded via embed.FS).
• Password Hashing: Argon2id in PHC format (golang.org/x/crypto/argon2).
• Authentication: Opaque session tokens (32 bytes crypto/rand, SHA-256 hashed in database).
• OIDC Verification: github.com/coreos/go-oidc/v3 with JWKS key caching.
• Containerization: Distroless multi-stage Docker build (gcr.io/distroless/static-debian12:nonroot).

Android Client (Kotlin 2.x & Compose)

• UI Framework: Jetpack Compose (Material Design 3).
• Architecture: MVVM with Unidirectional Data Flow (UDF) & StateFlow.
• Database: Room (KSP code generation).
• Network & Serialization: Retrofit 2 + OkHttp 4 + kotlinx.serialization.
• Background Sync: WorkManager (HiltWorker + CoroutineWorker).
• Dependency Injection: Hilt.
• Clock: Client-side Hybrid Logical Clock (HLC).