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:
parent
174aad535a
commit
a00db14cba
8 changed files with 482 additions and 96 deletions
51
docs/ARCHITECTURE.md
Normal file
51
docs/ARCHITECTURE.md
Normal 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 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue