Elkboard

Analyse- und Management-Dashboard für die Eishockey-Teams der Blue Elks (AEC – Aachener Eishockey Club).

---

Tech Stack

Layer	Technologie
Frontend	React 18, Vite, TypeScript, Tailwind CSS, shadcn/ui, Recharts, TanStack Query, Zustand
Backend	Node.js, Fastify, TypeScript, Prisma ORM
Datenbank	PostgreSQL 16
Auth	Oslo.js (Argon2id), Session-basiert, RBAC
Testing	Vitest, React Testing Library, Playwright (E2E)
Package Manager	pnpm (Monorepo)

---

Voraussetzungen

• Node.js >= 20.0.0
• pnpm >= 8.0.0
• PostgreSQL lokal oder via Docker

---

Quick Start

# Dependencies installieren
pnpm install

# Datenbank einrichten
cd packages/backend
pnpm prisma generate
pnpm prisma migrate dev
pnpm prisma db seed
cd ../..

# Development-Server starten
pnpm dev

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:3001

Test-Accounts (nach Seed)

Rolle	E-Mail	Passwort
ADMIN	admin@blueelks.de	admin123
DATA_MANAGER	manager@blueelks.de	manager123
USER	user@blueelks.de	userpass123

---

Projekt-Struktur

elkboard/
├── packages/
│   ├── backend/              # Fastify API + Prisma
│   │   ├── prisma/           # Schema, Migrations, Seed
│   │   └── src/
│   │       ├── routes/       # API Route Handler
│   │       ├── services/     # Business Logik (100% Coverage)
│   │       ├── middleware/    # Auth & Validation
│   │       └── lib/          # Auth Utilities (Hashing, Sessions)
│   ├── frontend/             # React + Vite
│   │   └── src/
│   │       ├── pages/        # Route-Seiten
│   │       ├── components/   # UI-Komponenten
│   │       ├── hooks/        # TanStack Query Hooks
│   │       ├── stores/       # Zustand Stores (Theme, Filter)
│   │       ├── services/     # API-Client
│   │       └── lib/          # Chart-Utilities, Helpers
│   └── shared/               # Zod-Schemas, TypeScript-Types
├── docs/                     # Feature-Dokumentation
│   ├── features/             # Dokumentation pro Feature
│   ├── Deployment.md         # Production Deployment Guide
│   ├── POSTGRESQL_SETUP.md   # Lokale DB-Einrichtung
│   └── Erweiterungen.md      # Feature-Ideen & Backlog
├── assets/                   # CSV-Import-Dateien
├── nginx/                    # Nginx-Konfiguration (Production)
├── docker-compose.yml        # Dev: PostgreSQL
├── docker-compose.prod.yml   # Production Container
└── .github/
    └── copilot-instructions.md  # AI Agent Instructions

---

Befehle

Development

pnpm dev              # Alle Dev-Server starten (Backend :3001, Frontend :5173)
pnpm build            # Alle Packages bauen
pnpm typecheck        # TypeScript-Check über alles

Testing

pnpm test             # Alle Tests ausführen
pnpm test:coverage    # Tests mit Coverage (100% für Services)

Code Quality

pnpm lint             # ESLint
pnpm lint:fix         # ESLint Auto-Fix
pnpm format           # Prettier formatieren
pnpm format:check     # Prettier prüfen

Datenbank

cd packages/backend
pnpm prisma studio                         # Prisma Studio (DB-Browser)
pnpm prisma migrate dev --name <name>      # Neue Migration erstellen
pnpm prisma generate                       # Prisma Client generieren
pnpm prisma db seed                        # Seed-Daten einspielen

Docker

# Nur PostgreSQL (Development)
docker-compose up postgres -d

# Production (alle Services)
docker-compose -f docker-compose.prod.yml up --build

# Images bauen und deployen
./build-and-push.sh     # Lokal bauen → Registry pushen
./deploy.sh quick       # VPS: Pull & Restart
./deploy.sh update      # VPS: Pull + Migrations

---

Feature-Dokumentation

Jedes implementierte Feature ist in docs/features/ dokumentiert:

Dokument	Inhalt
authentication.md	Auth-Flow, Rollen (ADMIN/DATA_MANAGER/USER), Session-Management
teams.md	Multi-Team, Altersklassen, Regelwerk (OT/SO/Punkte)
seasons.md	Saison-CRUD, aktive Saison, globaler Filter
matches.md	Spiel-Erfassung, Perioden, Resolution, Validierung
roster.md	Spieler-CRUD, Team-Zuordnung, DSGVO, Positions-Charts
game-data.md	Lineup, Tore, Strafen, Spieler-Statistiken
csv-import.md	Match- & Spieler-Import, Preview, Duplikat-Erkennung
calendar.md	Kalender-Events, Kategorien, Team-Filter
analytics.md	12 Charts, Dashboard-Widgets, Filter-System
admin.md	Benutzerverwaltung, Saison-Management
audit-log.md	Aktivitätslog, Retention Policy, Admin-Übersicht
league-crawler.md	Liga-Crawler, EHV/Rheinland Provider, Auto-Import
design-system.md	CSS-Klassen, Dark Mode, Chart-Farben, shadcn/ui

Weitere Dokumentation

Dokument	Inhalt
Deployment.md	Production Deployment (VPS, Docker, SSL, Nginx)
POSTGRESQL_SETUP.md	Lokale PostgreSQL-Einrichtung
Erweiterungen.md	Feature-Ideen & Backlog

---

Architektur

Datenfluss

Browser → React (Vite) → TanStack Query → Fastify API → Prisma → PostgreSQL
                                    ↑
                          Zod-Validierung (@elkboard/shared)

Auth-Flow

1. Register → User Status: PENDING
2. Admin-Approval → Status: APPROVED
3. Login → Session Cookie (30 Tage)
4. Protected Routes → requireAuth Middleware prüft Session + Status

Rollen

Rolle	Zugriff
Gast (nicht eingeloggt)	Dashboard (Read-Only)
USER	Dashboard, Analytics, Kader, Kalender (Read-Only)
DATA_MANAGER	+ Spiele, Teams, Saisons, Spieler, Import, Kalender-Events verwalten
ADMIN	+ Benutzerverwaltung, Aktivitätslog (Audit-Log)

Datenbank-Schema (14 Models)

User, Session, Team, Season, Match, Period, Player, TeamAssignment, GameParticipation, GameEvent, CalendarEvent, AuditLog, LeagueSource, CrawlRun

Vollständiges Schema: packages/backend/prisma/schema.prisma

---

Deployment

Production: https://elkboard.duckdns.org

Pre-built Container Images über Forgejo Registry, optimiert für Low-RAM VPS (0.5 GB).

Siehe docs/Deployment.md für die vollständige Anleitung.

---

Lizenz

MIT