# 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).