Innenstadt ID 100 - Companion App

Eine moderne Go-Webanwendung fuer kreative Dokumentationen mit Echo, PostgreSQL, MinIO (S3-kompatibel) und Meilisearch. Dieses Projekt ist ein nicht-kommerzielles künstlerisch-experimentelles Bachelorprojekt im Hochschulkontext der Universität Kassel. Teilnehmende laden im Rahmen von Aufgaben (Übungen zur urbanen Praxis und Innenstadtwahrnehmung) Fotos und Bilder hoch, um Wahrnehmungen des Stadtraums zu dokumentieren.

Features

• Upload und Galerie fuer kreative Beitraege
• WebP-Konvertierung und LQIP fuer schnelle Bildausgabe
• S3-kompatibler Storage ueber MinIO
• PostgreSQL fuer Daten und Migrations
• Meilisearch fuer City Autocomplete
• Hot Reload via Air
• Komplettes lokales Setup via Docker Compose

Voraussetzungen

• Go 1.24 oder hoeher
• Node.js 20 oder hoeher (Frontend Build)
• Docker und Docker Compose (empfohlen)

Schnellstart mit Docker Compose

Lokale Entwicklung (ohne nginx):

git clone https://github.com/dmnktoe/id-100.git
cd id-100
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d

Produktion (mit nginx):

docker compose up -d

Hinweise:

• In Produktion wird ein externes Netzwerk namens nginx-proxy erwartet.
• Der erste Start laedt deutsche Staedtedaten von GeoNames (ca. 10 MB).

Manuelle Entwicklung

go mod download
npm install

Start:

make run

Build:

make build
./bin/id-100

Konfiguration

Die Beispielwerte stehen in .env.example. Fuer die lokale Docker-Entwicklung wird .env.dev verwendet.

Wichtige Variablen:

Variable	Beschreibung
DATABASE_URL	PostgreSQL Verbindung fuer App und Migrationen
POSTGRES_USER	DB Nutzer (Docker)
POSTGRES_PASSWORD	DB Passwort (Docker)
POSTGRES_DB	DB Name (Docker)
S3_ACCESS_KEY	S3 Access Key (MinIO)
S3_SECRET_KEY	S3 Secret Key (MinIO)
S3_BUCKET	Bucket fuer Uploads
S3_ENDPOINT	Interner S3 Endpoint (Container)
S3_PUBLIC_URL	Externer S3 URL fuer Browser
MINIO_ROOT_USER	MinIO Root User
MINIO_ROOT_PASSWORD	MinIO Root Password
MEILI_MASTER_KEY	Meilisearch Master Key
GEOCODING_API_URL	Meilisearch API URL
SESSION_SECRET	Session Secret
ADMIN_USERNAME	Admin User
ADMIN_PASSWORD	Admin Passwort

Datenbank und Migrationen

Die Migrationen liegen in internal/database/migrations.

• 001_create_initial_tables.sql legt die Kern-Tabellen an.
• 002_insert_initial_deriven.sql fuellt die 100 Deriven.

Wenn du eigene Deriven verwenden willst, ersetze die Inhalte von 002_insert_initial_deriven.sql und starte den Stack neu.

API Endpunkte

Methode	Pfad	Beschreibung
GET	/health	Health Check (JSON)
GET	/api/stats	Statistik fuer Badges (JSON)
GET	/	Index der Deriven
GET	/id/:number	Detailansicht einer Derive
GET	/upload	Upload Formular
POST	/upload	Beitrag hochladen
POST	/upload/set-name	Spielernamen setzen
POST	/upload/contributions/:id/delete	Eigenen Beitrag loeschen
GET	/leitfaden	Leitfaden
GET	/impressum	Impressum
GET	/datenschutz	Datenschutz
GET	/werkzeug-anfordern	Werkzeug anfordern
POST	/werkzeug-anfordern	Werkzeug anfordern (Submit)
GET	/static/*	Statische Dateien

Makefile Kurzuebersicht

Die wichtigsten Targets stehen in Makefile:

make run
make build
make build-all
make test
make fmt
make vet
make docker-dev-up
make docker-dev-down
make docker-dev-rebuild
make docker-up
make docker-down

Frontend

npm run build
npm run build:dev
npm run watch

Build Output liegt in web/static/main.js.

Testing

Das Projekt nutzt Vitest fuer TypeScript/JavaScript Tests mit umfassender Coverage.

Tests ausfuehren

# Alle Tests ausfuehren
npm test

# Tests im Watch-Mode
npm run test:watch

# Tests mit UI
npm run test:ui

# Tests mit Coverage Report
npm run test:coverage

Projektstruktur

id-100/
├── cmd/id-100
├── internal
├── web
├── src
├── docker-compose.yml
├── docker-compose.dev.yml
├── Dockerfile
└── Makefile