refactor(structure): reorganize monorepo with projects, terraform hierarchy, and strict k8s namespace rules

2026-10-12 13:49:41 +02:00
parent 4831147087
commit 8f01b75bd6
4766 changed files with 551 additions and 91 deletions
@@ -0,0 +1,76 @@
+# AGENTS.md — Grabengasse 7 Home Portal (`grabengasse`)
+
+> [!NOTE]
+> **Domain**: Local climate, environment, and smart home portal for Grabengasse 7.  
+> **Live Production URL**: `https://grabengasse7.de`  
+> **Kubernetes Manifests**: `k8s/grabengasse/` (Namespace: `grabengasse`)  
+> **Images**:  
+> - Frontend: `registry.haumdaucher.de/website/grabengasse_frontend:latest`  
+> - Backend: `registry.haumdaucher.de/website/grabengasse_backend:latest`  
+> **Source Location**: `projects/grabengasse/`
+
+---
+
+## 🏛️ Architecture & Tech Stack
+
+1. **Frontend (`frontend/`)**:
+   - **Framework**: Vue 3 (Composition API) + Vite + TypeScript.
+   - **Styling**: Retro-chic aesthetic with pixel art accents, glassmorphic cards, and an optional CRT scanline toggle.
+   - **Data Visualization**: Chart.js / Vue-Chartjs / Apexcharts for 24h temperature, humidity, wind, solar, and rain telemetry.
+   - **Serving Runtime**: Nginx (`nginx:alpine`) in Docker.
+
+2. **Backend (`backend/`)**:
+   - **Framework**: FastAPI (Python 3.11).
+   - **Telemetry Source**: Direct HTTP queries to cluster Prometheus (`http://prometheus-operator-kube-p-prometheus.monitoring.svc.cluster.local:9090`) aggregating metrics from the Shelly WS90 weather station.
+   - **Endpoints**:
+     - `GET /healthz`: Liveness and readiness probe.
+     - `GET /api/v1/weather/current`: Live weather telemetry (temperature, humidity, wind speed, solar radiation, rain).
+     - `GET /api/v1/weather/history`: Historical timeseries for 24h graphing.
+
+3. **Kubernetes Ingress & Routing (`k8s/grabengasse/`)**:
+   - Ingress Host: `grabengasse7.de` with Traefik ingress controller and `cert-manager` TLS.
+   - `/` &rarr; `grabengasse-frontend` (Port 80)
+   - `/api` &rarr; `grabengasse-backend` (Port 8000)
+
+---
+
+## 🛠️ Build & Deployment Commands
+
+```bash
+cd projects/grabengasse
+make compile          # Build frontend static assets (npm run build)
+make build            # Build both frontend and backend Docker images (linux/amd64)
+make push             # Push images to registry.haumdaucher.de
+make deploy           # Apply k8s manifests and rollout restart pods
+```
+
+---
+
+## 📁 Repository Structure
+
+```
+projects/grabengasse/
+├── Makefile                    # Coordinated multi-service build and deploy
+├── AGENTS.md                   # This handbook
+├── README.md                   # Project overview
+├── frontend/                   # Vue 3 SPA
+│   ├── Dockerfile
+│   ├── Makefile
+│   ├── nginx.conf
+│   ├── package.json
+│   ├── src/
+│   │   ├── App.vue             # Weather dashboard layout & state
+│   │   ├── components/         # Weather gauges, telemetry cards & retro CRT overlay
+│   │   └── scripts/            # generate_icons.py (Pixel art icon generator)
+│   └── public/                 # Static icons, manifest, and service worker
+└── backend/                    # FastAPI microservice
+    ├── Dockerfile
+    ├── Makefile
+    ├── requirements.txt
+    ├── main.py                 # FastAPI application entrypoint
+    ├── config.py               # CORS & environment configuration
+    ├── routers/
+    │   └── weather.py          # /api/v1/weather routes
+    └── services/
+        └── prometheus.py       # Prometheus query client
+```