agw/AGENTS.md

Agent Instructions

These instructions are authoritative for work in this repository.

Project Overview

Abgeordnetenwatch PWA + Backend — a progressive web app that lets users follow Bundestag/Landtag topics and politicians, displaying a personalized feed of votes with push notifications for new votes. The PWA queries the Abgeordnetenwatch API directly for browsing; the backend polls for new votes and sends Web Push notifications to subscribed devices.

Stack — PWA (root)

Layer	Tool
Runtime	Bun
Build	Vite + TanStack Router Plugin + vite-plugin-pwa (injectManifest)
UI	React 19 + shadcn/ui + Tailwind CSS v4
Routing	TanStack Router (file-based, src/routes/app/ for mobile)
State	Zustand (ephemeral UI), PGlite (persistent data via IndexedDB)
Validation	Zod
Code Quality	Biome + simple-git-hooks + lint-staged
Testing	Vitest + Testing Library

Stack — Backend (server/)

Layer	Tool
Runtime	Node 22 (production via tsx), Bun (development)
Framework	Hono + @hono/node-server
Database	PostgreSQL + Drizzle ORM
Job Queue	pg-boss (cron: poll-checker every 15 min)
Push	web-push (VAPID)
Validation	Zod
Testing	Vitest

Architecture

src/                          PWA source
├── features/                 Feature modules
│   ├── home/                 Home tab (placeholder)
│   ├── bundestag/            Bundestag tab: DIP + AW feed, configure (topics + reps)
│   ├── landtag/              Landtag tab: representatives by geo-detection, configure
│   ├── feed/                 Shared feed components (FeedList, FeedItemCard, useFeed)
│   ├── location/             Geo-detection, Bundestag mandate caching, party metadata
│   ├── topics/               useTopics hook (shared by configure pages)
│   └── settings/             Settings page (notifications, location, updates)
├── shared/                   Shared code
│   ├── components/           representative-list, topic-toggle-list
│   │   └── ui/               shadcn components
│   ├── db/                   PGlite client, migrations, data-access modules, DbProvider
│   ├── hooks/                use-device-id, use-follows, use-push, use-pwa-update
│   └── lib/                  aw-api, dip-api, constants, push-client, utils
├── routes/                   TanStack Router file-based routes
│   ├── app/                  Tabs: Home / Bundestag / Landtag / Einstellungen
│   │   ├── bundestag/        index (feed) + configure sub-route
│   │   └── landtag/          index (reps) + configure sub-route
│   └── index.tsx             Redirect → /app/home
├── sw.ts                     Custom service worker (precache + push handlers)
├── app.tsx                   RouterProvider
├── app.css                   Tailwind v4 + shadcn theme
└── main.tsx                  Entry point

server/                       Backend source
├── src/
│   ├── features/push/        Push subscription routes + service
│   ├── shared/
│   │   ├── db/               Drizzle client + schema (push_subscriptions, device_follows, seen_polls, politician_mandates)
│   │   ├── jobs/             pg-boss client + poll-checker cron
│   │   └── lib/              env validation, AW API client (server-side), web-push helper
│   ├── app.ts                Hono app assembly
│   └── index.ts              Entry point
├── drizzle.config.ts
├── package.json
└── .env.example              DATABASE_URL, PORT, VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT

Deployment

• PWA: static files deploy to Uberspace at /var/www/virtual/<user>/html/agw/
• Backend: deployed as a supervisord service on Uberspace at ~/services/agw-backend/
• Backend API is reverse-proxied at /agw/api/ via uberspace web backend
• ./deploy.sh builds and deploys both PWA and backend
• Apache .htaccess handles SPA routing

Commands — PWA (root)

• bun dev — start dev server
• bun run build — production build
• bun run test — run tests
• bun run lint — biome check
• bun run lint:fix — biome auto-fix

Commands — Backend (server/)

• bun dev — start with file watching
• bun start — start with Node + tsx (production)
• bun run db:generate — generate Drizzle migrations
• bun run db:migrate — run Drizzle migrations
• bun run test — run tests
• bun run lint — biome check