Tronax
cdc0c785b9
Document the four features that landed on main in b44bc8c..85c790e: - AGENTS.md: post-MVP section now covers server-driven auth discovery (GET /api/config, AUTH_PASSWORD_ENABLED 403 enforcement, OIDC_GENERIC_DISPLAY_NAME), the settings screen with GET/PUT /api/me, and the critical Android sync/data-safety fixes (pull-all-lists, client HLC tick per server op, no destructive migration, ProGuard rules). Repo structure updated (httpapi config.go/me.go, ui/settings), roadmap entries added, open-points list extended with test backlog for the new endpoints. - API.md: new sections for GET /api/config (public) and GET/PUT /api/me; 403 responses documented for register/login when password auth is off. - SYNC.md: client pull loop (every tracked list, op_log pruning) and the client HLC discipline (tick per incoming server op) that keeps LWW correct across devices with skewed clocks. - README: highlights for auth discovery/OIDC-only mode and the settings screen.
96 lines
3.8 KiB
Markdown
96 lines
3.8 KiB
Markdown
# Mitbringsl 🛒
|
||
|
||
> **Local-First Einkaufslisten-App (Bring-Alternative, werbefrei & datensparsam).**
|
||
|
||
Mitbringsl ist eine moderne, schnelle und werbefreie Einkaufslisten-App mit **Local-First Synchronization**. Die App funktioniert vollständig offline und synchronisiert Änderungen automatisch, sobald eine Verbindung besteht — ohne Datenverlust oder Konflikte.
|
||
|
||
---
|
||
|
||
## 🌟 Highlights & Features
|
||
|
||
- 📱 **Android App**: Kotlin 2.x, Jetpack Compose Material 3, Room, Hilt, WorkManager.
|
||
- 🔌 **Local-Only by Default**: Kein Account nötig — die App startet direkt ohne Login; Sync & Account sind optional (auch Self-Hosted, Server-URL in der App konfigurierbar).
|
||
- 👥 **Geteilte Listen**: Listen per 8-Zeichen-Invite-Code teilen und gemeinsam bearbeiten; Membership wird serverseitig bei jedem Sync geprüft.
|
||
- ⚡ **Local-First Sync Engine**: Hybrid Logical Clock (HLC), append-only `op_log`, Last-Write-Wins (LWW) Projektionen, Idempotente Push/Pull-Algorithmen.
|
||
- 🔐 **Datenschutz & Auth**: Argon2id Passwort-Hashing, opaque Session-Tokens, OIDC-Unterstützung (Google & eigene IdPs wie Authentik/Keycloak) — Login-Methoden werden serverseitig per `/api/config` entdeckt, Passwort-Login lässt sich per `AUTH_PASSWORD_ENABLED=false` komplett abschalten.
|
||
- ⚙️ **Settings & Themes**: Account-/Profil-Verwaltung (`/api/me`), Theme-Umschalter (System/Hell/Dunkel), lokaler Daten-Reset — alles direkt in der App.
|
||
- 🚀 **Go Backend**: Stdlib `net/http` Routing (Go 1.26), PostgreSQL 16 (`pgxpool`), `pg_trgm` Fuzzy Autocomplete.
|
||
- 🛡️ **Deployment**: Multi-Stage Docker Container, Caddy Reverse Proxy mit automatischem HTTPS / Standalone & Behind-Proxy Modi.
|
||
|
||
---
|
||
|
||
## 🏗️ Repository-Struktur
|
||
|
||
```
|
||
mitbringsl/
|
||
├── backend/ # Go REST API Backend
|
||
│ ├── cmd/ # Server & Migrate Binaries
|
||
│ ├── internal/ # Auth, Sync (HLC), Store (pgx), HTTP API
|
||
│ ├── migrations/ # SQL Migrationen (iofs-embedded)
|
||
│ └── Dockerfile # Multi-Stage Build (golang:1.26 -> distroless)
|
||
├── android/ # Android Kotlin + Compose App
|
||
│ ├── app/src/ # Room DB, Retrofit API, WorkManager, Hilt, Compose UI
|
||
│ └── build.gradle.kts
|
||
├── deploy/ # Docker Compose & Caddy Setup
|
||
│ ├── docker-compose.yml
|
||
│ ├── Caddyfile / Caddyfile.behind-proxy
|
||
│ └── .env.example
|
||
└── docs/ # Architektur- & Protokoll-Dokumentation
|
||
├── ARCHITECTURE.md # Gesamtarchitektur & Systemdesign
|
||
├── SYNC.md # Sync-Protokoll & HLC-Spezifikation
|
||
└── API.md # REST API Dokumentation
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Quickstart: Backend & Stack lokal starten
|
||
|
||
### 1. Backend lokal bauen & testen
|
||
```bash
|
||
cd backend
|
||
go build ./...
|
||
go vet ./...
|
||
go test ./...
|
||
```
|
||
|
||
Integrationstests (Invite/Join/Membership, E2E über HTTP) laufen gegen eine
|
||
wegwerfbare PostgreSQL-Instanz:
|
||
```bash
|
||
docker run -d --name mitbringsl-test-pg -e POSTGRES_USER=app \
|
||
-e POSTGRES_PASSWORD=testpw -e POSTGRES_DB=appdb -p 55432:5432 postgres:16-alpine
|
||
cd backend
|
||
TEST_DATABASE_URL="postgres://app:testpw@localhost:55432/appdb?sslmode=disable" go test ./...
|
||
docker rm -f mitbringsl-test-pg
|
||
```
|
||
|
||
### 2. Stack per Docker Compose starten
|
||
```bash
|
||
cd deploy
|
||
cp .env.example .env
|
||
# Passwörter in .env anpassen
|
||
docker compose up -d --build
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 Android App bauen
|
||
|
||
```bash
|
||
cd android
|
||
./gradlew assembleDebug
|
||
./gradlew test
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Dokumentation
|
||
|
||
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) – Architektur & Systemdesign
|
||
- [SYNC.md](docs/SYNC.md) – Synchronisationsprotokoll & HLC-Spezifikation
|
||
- [API.md](docs/API.md) – REST API Endpoint-Referenz
|
||
- [AGENTS.md](AGENTS.md) – Projektstand & Architekturentscheidungen für KI-Agenten
|
||
|
||
---
|
||
|
||
## 📄 Lizenz
|
||
MIT License
|