Tronax
a00db14cba
- 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 ✅
51 lines
3.1 KiB
Markdown
51 lines
3.1 KiB
Markdown
# 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).
|