Phase F: NetworkMonitor, offline banner, README & architecture docs

- NetworkMonitor: ConnectivityState Flow using ConnectivityManager.NetworkCallback
- ListsScreen & ViewModel: live offline indicator banner when disconnected
- Documentation:
  - docs/ARCHITECTURE.md: system design & tech stack overview
  - docs/SYNC.md: HLC timestamping, op_log outbox & LWW projection specification
  - docs/API.md: REST API endpoint specification
  - README.md: quickstart guide for backend, docker compose & Android app
- Verification: backend & android test suites 100% green 
This commit is contained in:
Tronax 2026-08-05 20:14:04 +02:00
parent 174aad535a
commit a00db14cba
Signed by: Tronax
SSH key fingerprint: SHA256:2pKKXDZucWvaF/GzXNz0FY53EAO1YDLN80bqS+TTz/o
8 changed files with 482 additions and 96 deletions

51
docs/ARCHITECTURE.md Normal file
View file

@ -0,0 +1,51 @@
# 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 clients 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).