infrapuzzle/projects/grabengasse/AGENTS.md

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.
   • / → grabengasse-frontend (Port 80)
   • /api → grabengasse-backend (Port 8000)

---

🛠️ Build & Deployment Commands

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