Docs: catch up to auth discovery, settings screen and sync fixes

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.

2026-08-22 09:45:45 +02:00

3.8 KiB

Raw Blame History

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

cd backend
go build ./...
go vet ./...
go test ./...

Integrationstests (Invite/Join/Membership, E2E über HTTP) laufen gegen eine wegwerfbare PostgreSQL-Instanz:

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

cd deploy
cp .env.example .env
# Passwörter in .env anpassen
docker compose up -d --build

📱 Android App bauen

cd android
./gradlew assembleDebug
./gradlew test

📖 Dokumentation

ARCHITECTURE.md – Architektur & Systemdesign
SYNC.md – Synchronisationsprotokoll & HLC-Spezifikation
API.md – REST API Endpoint-Referenz
AGENTS.md – Projektstand & Architekturentscheidungen für KI-Agenten

📄 Lizenz

MIT License

3.8 KiB Raw Blame History Unescape Escape