100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# 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
|