vikingowl
0b797aec66
- CLAUDE.md: correct stale Woodpecker/submodules claims; note registry.itsh.dev's attestation requirement and the docker-container driver prerequisite so future contributors don't rediscover the issue. - .gitlab-ci.yml: export SOURCE_DATE_EPOCH from commit time so the rewrite-timestamp=true buildx flag produces genuinely reproducible images (layer digests stable across rebuilds of the same commit).
3.0 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
Marktvogt is a platform for medieval markets (Mittelaltermärkte) in the DACH region. It connects visitors, merchants, artists, camp groups, and organizers — replacing fragmented Facebook groups, phone calls, and scattered websites.
All planning documents are in planning/. Read 17-roadmap.md for the phased feature plan and 15-mvp.md for current MVP scope.
Architecture
Monorepo at gitlab.com/vikingowl/marktvogt.de. Components are regular directories (not git submodules):
backend/— Go REST API + WebSocket (chat). PostgreSQL (+ PostGIS), Redis, S3 (self-hosted on itsh.dev).web/— SvelteKit + Tailwind 4. SSR for SEO. Consumes the Go API.app/— Flutter mobile app (Android + iOS). Consumes the Go API.admin/— Separate admin dashboard (own repo, added later).
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Go, PostgreSQL, PostGIS, Redis, S3 |
| Web Frontend | SvelteKit, Tailwind 4 |
| Mobile | Flutter |
| Auth | Custom (Go libs), E-Mail+PW / Magic Link / OAuth / 2FA |
| Payments | Stripe Connect |
| LLM | OpenRouter |
| CI/CD | GitLab CI (gitlab.com) — evaluation vs Woodpecker; sister project infinity-tales still on Woodpecker |
| Hosting | Kubernetes (itsh.dev) |
| Monitoring | Prometheus, Loki, Grafana, Sentry |
Key Domain Concepts
- 6 roles: Gast (anonymous), User (registered), Händler (merchant), Künstler (artist), Lager (reenactment camp group), Veranstalter (organizer)
- Groups: All applicants (Händler/Künstler/Lager) operate as groups. A solo merchant is a one-person group. Applications always go through groups.
- Veranstalter is the central role — creates markets, manages plots, reviews applications, configures tickets.
- Mitarbeiter (staff) is a sub-role under Veranstalter with granular permissions.
Development Conventions
- All planning docs use ASCII (no umlauts) for cross-platform compatibility.
- API design: REST for CRUD, WebSocket for real-time chat.
- Auth is custom-built using Go libraries (no external auth provider).
- Offline capability required for QR ticket validation and venue maps.
Current Status
Project is in active development as of 2026-04-18. backend/, web/, and app/ contain working code (Go API scaffolding + auth, SvelteKit pages, Flutter iOS/Android skeleton). Refer to planning/17-roadmap.md for feature sequencing and planning/15-mvp.md for current MVP scope.
Container registry is registry.itsh.dev/vikingowl/marktvogt.de/{backend,web} — a hosted Zot-backed registry that requires attestations on every pushed image. Builds must use buildx's docker-container driver (not the default docker driver). See .gitlab-ci.yml for the working pattern.