# MetalCircle

MetalCircle ist eine private, invite-only Community-Plattform rund um Heavy-Metal-Konzerte. Mitglieder verwalten einen Konzertkalender, sehen Konzertdetails, bekunden Teilnahme oder Interesse, kommentieren Konzerte und pflegen Profile. Dazu gehören Fotos, Freundschaften, Direktnachrichten, Patches sowie Web- und Android-App. Automatische Android-Pushs für Anfragen, Nachrichten und Einladungen sind nach Firebase-Backend-Einrichtung aktivierbar. Die Oberfläche unterstützt DE/EN über einen Umschaltbutton.

Der Repository-Name ist historisch noch `pingu-concerts`. Das ist beabsichtigt und wird hier nicht automatisch umbenannt.

## Technologie

- FastAPI und Uvicorn (Python-Backend)
- PostgreSQL mit SQL-Schema und versionierten Migrationen
- Server-renderte HTML-Templates mit Jinja2 sowie CSS und JavaScript
- Docker Compose für die lokale Web- und Datenbankumgebung
- Capacitor 6 / Android mit Paket-ID `de.pinguholic.concerts`
- Firebase Cloud Messaging für Android-Registrierung und Benachrichtigungen
- Nominatim für die optionale Venue-Suche und Geocoding-Anreicherung
- Gitea REST API für den Bugreporter

## Repository-Überblick

```text
app/             FastAPI, Templates, Static Assets und Tests
db/init/         Initialschema für eine neue PostgreSQL-Datenbank
db/migrations/   Nachträgliche, reproduzierbare Schemaänderungen
android/         Capacitor-Projekt und Android-App
compose*.yml     Containerdefinitionen und optionale Push-/Pre-Production-Konfiguration
img/             Projektgrafiken
```

## Lokal entwickeln

Voraussetzung sind Docker und Docker Compose. Eine lokale Konfiguration wird aus `.env.example` erstellt und mit eigenen Entwicklungswerten ergänzt. Danach:

```bash
cp .env.example .env
COOKIE_SECURE=false docker compose up --build
```

Die Anwendung ist anschließend unter `http://localhost:8080` erreichbar. Stoppen geht mit `docker compose down`; Logs zeigt `docker compose logs -f web`.

Das Schema wird beim Start aus `db/init/01_initial.sql` angelegt und von den Migrationen bzw. der Startup-Schema-Prüfung ergänzt. Migrationen nie nur manuell in einer Datenbank ausführen.

## Konfiguration und Daten

Die erwarteten Variablen stehen in `.env.example`: PostgreSQL-Zugang, Initial-Admin, `COOKIE_SECURE` sowie die optionalen Gitea-Werte `GITEA_URL`, `GITEA_TOKEN`, `GITEA_OWNER` und `GITEA_REPO`. `.env`, Firebase-`google-services.json`, private Schlüssel, Datenbank-Dumps und lokale Uploads gehören nicht in Git. Es dürfen ausschließlich lokale Testwerte verwendet werden.

## Android

```bash
cd android
npm install
npm run sync
npm run build
```

Die App bleibt unter der Package ID `de.pinguholic.concerts`. Für einen lokalen Firebase-/Web-Test benötigt das Android-Modul die lokale, ignorierte `android/android/app/google-services.json`. Diese Datei und ihre Credentials werden nicht veröffentlicht.

## Interner Workflow

Änderungen werden in einem Arbeitsbranch geprüft und als nachvollziehbarer Commit nach Review in `main` übernommen. Gitea Issues dienen als führendes Bug-System; der integrierte Reporter legt Issues über den dedizierten Bot an.

Ausführliche Entwickler-, Architektur-, Deployment- und Betriebsdokumentation befindet sich im [Gitea Wiki](../../wiki). Die [Wiki-Quellen](docs/wiki/Home.md) sind zusätzlich versioniert. Siehe [Firebase-Einrichtung](docs/wiki/Firebase.md), [Push-Ablauf](docs/wiki/Push-Notifications.md), den [ChatGPT-Prompt](docs/wiki/Firebase-Setup-Prompt.md) und die konfigurierbaren [Alpha-/Beta-/Early-Bird-Stufen](docs/wiki/Badges-and-Patches.md).