120 lines
6.3 KiB
Markdown
120 lines
6.3 KiB
Markdown
# AGENTS.md — Haumdaucher Official Website (`haumdaucherde`)
|
|
|
|
> [!NOTE]
|
|
> **Domain**: Official website and community platform for Haumdaucher Regensburg (`HAUMDAUCHER Wurst und Spezialitäten n.e.V.`).
|
|
> **Live Production URL**: `https://haumdaucher.de`
|
|
> **Kubernetes Manifest**: `k8s/haumdaucher/haumdaucher.yaml` (Namespace: `haumdaucher`)
|
|
> **Container Image**: `registry.haumdaucher.de/haumdaucher-website:latest`
|
|
> **Source Location**: `projects/haumdaucherde/`
|
|
|
|
---
|
|
|
|
## 🚨 Rules & Principles
|
|
**1. Infrastructure as Code is rule #1.** Manual creation of cloud resources (e.g., via `gcloud` or Console) is forbidden. Use Terraform/OpenTofu located in `terraform/`.
|
|
|
|
**2. Agental Protocol (Git & Deployment):**
|
|
- Never deploy to production before changes are verified with tests (`npm test -- --run`) and static build (`npm run build`).
|
|
- Standard deployment is driven via `make deploy` or `./deploy.sh`.
|
|
|
|
---
|
|
|
|
## 🦢 Project Essence
|
|
**Haumdaucher** is a community project from Regensburg, Germany. The website represents the "HAUMDAUCHER Wurst und Spezialitäten n.e.V." (nicht eingetragener Verein). It is designed to be humorous, culturally rich, and technically "surprising."
|
|
|
|
---
|
|
|
|
## 🎨 Design Principles
|
|
- **Vibrant Aesthetics**: Each theme feels like a distinct experience.
|
|
- **Glassmorphism**: Use `backdrop-filter` and semi-transparent backgrounds for a premium feel.
|
|
- **Micro-interactions**: Subtle entrance animations and consistent hover states.
|
|
- **Accessibility**: Mobile-first design with safe-area support for PWA usage on iOS/Android (`max-width: 375px`).
|
|
|
|
---
|
|
|
|
## ⚖️ Legal & Compliance (n.e.V.)
|
|
Maintaining the legal section is critical for German compliance (§ 5 DDG).
|
|
- **Entity Type**: The club is a **nicht eingetragener Verein (n.e.V.)**. Do NOT add Registry data (Registergericht/Nummer).
|
|
- **Mandatory Impressum Fields**:
|
|
- Full Name: `HAUMDAUCHER Wurst und Spezialitäten n.e.V.`
|
|
- Vertretungsberechtigter: `Moritz Graf (1. Vorstand)`
|
|
- Ladungsfähige Anschrift: `Grabengasse 7, 93059 Regensburg`
|
|
- Kontakt: `Telefon: 094183065717, E-Mail: info@haumdaucher.de`
|
|
- **Privacy (DSGVO)**: The website uses **Google Firebase Authentication**. The privacy policy must disclose the data processing by Google Ireland Limited and the US data transfer details.
|
|
|
|
---
|
|
|
|
## 🛠️ Technical Specifications
|
|
- **Framework**: Vue 3 (Composition API) + Vite + TypeScript.
|
|
- **State Management**: Centralized in `App.vue` using standard `ref` hooks and composables (`useAuth.ts`).
|
|
- **Theming System**:
|
|
- Driven by `data-theme` attribute on `:root`.
|
|
- Defined in `src/assets/styles/global.css`.
|
|
- Themes: `Classic` (Light), `Dark` (Premium Charcoal/Gold), `NAT` (Boar Easter Egg), `Win95`, `Unicorn`, `Luxury`.
|
|
- **Localization**:
|
|
- Centralized in `src/locales/i18n.ts`.
|
|
- Language: `de` (Standard German) only.
|
|
|
|
---
|
|
|
|
## 🚢 Deployment & DevOps
|
|
|
|
Standard commands:
|
|
```bash
|
|
cd projects/haumdaucherde
|
|
make test # Run Vitest unit tests (npm test -- --run)
|
|
make compile # Static build to dist/ (npm run build)
|
|
make build # Docker build using ./deploy.sh (extracts Firebase config from terraform)
|
|
make deploy # Apply k8s/haumdaucher/haumdaucher.yaml and rollout restart
|
|
```
|
|
|
|
**Workflow Details:**
|
|
1. **Cluster Sync**: Ensures the `haumdaucher` namespace exists in Kubernetes.
|
|
2. **Config Extraction**: Fetches Firebase credentials directly from Terraform outputs (`terraform output -json firebase_config` in `terraform/`).
|
|
3. **Build Pipeline**: Docker multi-stage build (`node:lts-alpine` builder → `nginx:stable-alpine` runtime) targeting `linux/amd64`.
|
|
4. **Distribution**: Pushes the image to `registry.haumdaucher.de/haumdaucher-website:latest`.
|
|
5. **Kubernetes Rollout**: Applies `k8s/haumdaucher/haumdaucher.yaml` and executes `kubectl rollout restart deployment/haumdaucher-website -n haumdaucher`.
|
|
|
|
---
|
|
|
|
## 📁 Repository Structure
|
|
|
|
```
|
|
projects/haumdaucherde/
|
|
├── Dockerfile # Multi-stage container build (Node builder -> Nginx runtime)
|
|
├── Makefile # Standard make targets (compile, dev, test, build, deploy)
|
|
├── deploy.sh # Deployment script with Terraform config extraction
|
|
├── package.json # Dependencies and scripts (Vue 3, Vite, Vitest, VueFire)
|
|
├── vite.config.ts # Vite configuration with PWA plugin
|
|
├── tsconfig.json # TypeScript base configuration
|
|
├── index.html # HTML entrypoint
|
|
├── k8s-manifests.yaml # Local copy of Deployment, Service & Ingress manifests
|
|
├── public/ # Static assets (PWA icons, theme logos in images/)
|
|
├── src/ # Vue 3 source code
|
|
│ ├── App.vue # Top-level shell and theme state
|
|
│ ├── firebase.ts # Firebase client SDK initialization
|
|
│ ├── main.ts # Vue entrypoint
|
|
│ ├── components/ # Reusable UI components & sections
|
|
│ ├── composables/ # useAuth authentication composable
|
|
│ ├── locales/ # Centralized i18n German translations
|
|
│ └── assets/ # Styles (global.css) and logos
|
|
├── terraform/ # Terraform IaC for Firebase project & auth config
|
|
├── user_creation/ # Declarative Google Apps Script for user provisioning
|
|
├── mail_forwarding/ # Google Apps Script for haumdaucher.de email routing
|
|
└── scripts/ # Helper scripts (setup-local-env.sh, manage_secrets.py)
|
|
```
|
|
|
|
---
|
|
|
|
## 🤖 Sub-module Documentation
|
|
Certain independent sub-modules contain their own highly specific operational guidelines. Always consult them when working in those directories:
|
|
- **`user_creation/AGENTS.md`**: Contains critical safeguards and architectural details for the declarative Google Apps Script that provisions Firebase users from Google Sheets.
|
|
- **`mail_forwarding/AGENTS.md`**: Outlines mail forwarding rules and clasp deployment.
|
|
|
|
---
|
|
|
|
## 🕹️ The Haumdaucher Game
|
|
- **Engine**: HTML5 Canvas rendering. Game style changes dynamically based on the site's active theme.
|
|
- **Unlocking NAT Mode**:
|
|
- **Natural**: Reach Level 10.
|
|
- **Backdoor**: Single 1x1 pixel in the bottom-left corner. Type `nat mode` into the prompt.
|