A centralized event calendar for Oberhausen, Germany.
It collects the events of Einrichtungen (institutions) and serves them through a public website, embeddable widgets, and an authenticated HTTP JSON API.
An Einrichtung is the organisation that publishes an event here and vouches for it. Its editors enter events themselves, and it may also deliver them through Quellen (sources): import feeds fetched twice a day (oberhausen.de, superhausen.de, kitev.de, OWT / et4, drucklufthaus.de; listed with their Einrichtung in convex/integrations/registry.ts).
Imported events mirror their Quelle's last successful run and are read-only; events the Quelle stops listing stay reachable but leave feeds and search.
Live: https://kalender-oberhausen.de
- Frontend: React 19, Vite, TanStack Router (file-based), TypeScript (strict), Tailwind CSS v4, Base UI primitives
- Backend: Convex (database, server functions, realtime, cron jobs, HTTP endpoints)
- Auth:
@convex-dev/authwith one-time sign-in links by email (no passwords, no self sign-up), mails via Resend - Quality: Biome (lint + format)
- Package manager: Bun
- Hosting: Cloudflare Pages (frontend) + Convex (backend), deployed via GitHub Actions
bun install
bun run devAuth needs a signing keypair set on your Convex deployment. Generate the env block and paste it into the Convex dashboard (it fills JWT_PRIVATE_KEY / JWKS; set your own API_KEY):
bun scripts/setup_convex_env.tsSign-in links point at SITE_URL, so also set it to where the frontend runs (e.g. http://localhost:5173).
Create the topic categories and invite an admin, then try an import:
bun x convex run seed:seedCategories
bun x convex run seed:inviteAdmin '{"email":"admin@example.com","name":"Admin"}'
bun x convex run integrations/queue:request '{"sources":["owt"]}'Accounts have no passwords: admins invite people by email (a sign-in link valid for 7 days), and everyone signs in by requesting a one-time link on /login (valid for an hour). Without RESEND_API_KEY, the usual dev setup, mails are only written to the Convex logs; bun x convex run auth:signInLink '{"email":"admin@example.com"}' prints a working sign-in link for any existing account.
bun run dev- Vite + Convex dev togetherbun run build- type-check the frontend, tooling, and Convex backend, then build the production bundlebun run typecheck- TypeScript checks for the frontend, tooling, and Convex backendbun run check:fix- Biome lint + format auto-fixbun x convex run seed:seedCategories- set the topic categories; dropped ones still in use stay until the imports re-categorised their events, then run it againbun x convex run seed:clear- clear every table except Einrichtungen, Quellen, categories and accounts (optionally'{"tables":[...]}')bun x convex run seed:inviteAdmin '{"email":"…","name":"…"}'- create an admin account and mail it an invitationbun x convex run auth:signInLink '{"email":"…"}'- print a sign-in link for an existing account, valid for an hour (replaces the account's earlier link)bun x convex run demo:seed/demo:clear- dev only: three fictional Einrichtungen with editor accounts (demo+<slug>@example.com, never mailed; sign in throughauth:signInLink) and hand-entered eventsbun x convex run integrations/queue:request '{"sources":["<slug>"]}'- queue imports (oberhausen|superhausen|kitev|owt|druckluft; withoutsourcesall of them). Every 12 hours the cron queues all of them; imports run one at a time, and a source already queued or running is not queued twicebun x convex run duplicates:detectAll '{"cursor":null}'- rescan every event for duplicate suggestions, e.g. after changing the matching rules inconvex/lib/similarity.ts
/embed renders the calendar for an iframe; the builder (/admin/einbinden and the "Für Veranstalter" page) writes its URL. Parameters (comma-separated slugs):
werkzeuge- tools beside the list:suche,filter,kalender, orkeinekategorien/ohne-kategorien,einrichtungen/ohne-einrichtungen- restrict the events showntheme- one of the themes insrc/themes.ts
Older published forms (layout, ansicht, design, English and earlier German scope names) keep working; src/features/embed/url.ts lists them.
Read-only JSON API for the Chatpott chatbot. Every request needs Authorization: Bearer <API_KEY>. Events are identified by their ULID (id); pageUrl is the canonical page (SITE_URL/veranstaltung/<id>/<slug>). Descriptions are plain text: blank lines separate paragraphs, list items start with - or 1..
GET /api/events/search-query,fromMs,toMs(default today to +90 days),limit(1-25, default 8),sort(soonest|relevance), comma-separatedcategoriesAny,categoriesAll,categoriesExclude,institutionsAny,institutionsExclude(at most 10 slugs each). A time word inquery(heute,morgen,Wochenende,Freitag,nächste Woche,Dezember, ...; relative to the day offromMs) narrows the window to its days. Returns{ events, total, hasMore, dataHorizon }; each event hasid,pageUrl,title,subtitle,occurrences(at most 20),moreOccurrences(further dates in the window),locationName,organizer,categories,institution: { slug, name },source: { slug, name }(imported events only),sourceUrl,teaser,hasImage. When a duplicate of an event is linked to another listing, only the highest-ranked listing shows on a day.GET /api/events/by-id?id=<ulid>- optionalfromMs,toMs. Returnsid,pageUrl,title,subtitle,description,organizer,locationName,locationAddress,price,ticketUrl,sourceUrl,imageUrl,imageCredit,listed(false once its Quelle stopped listing an imported event),institution,source(imported events only),categories,occurrences(at most 25),totalOccurrences.GET /api/categories-{ categories: [{ slug, name, description }], institutions: [{ slug, name, url }] }.
Breaking changes against the previous API: sourcesAny / sourcesExclude became institutionsAny / institutionsExclude; every event names its Einrichtung as institution: { slug, name }, while source: { slug, name } only appears on imported events and names the Quelle they were taken from; /api/categories returns institutions instead of sources. The category slugs changed with the new topic set (e.g. konzert → musik, theater → buehne); read them from /api/categories. Earlier: slug became id plus pageUrl; /api/events/by-slug?slug= became /api/events/by-id?id=; info was split into subtitle, organizer, price, ticketUrl and imageCredit; importSource is gone.
Pushes to main trigger .github/workflows/deploy.yml, which runs convex deploy (backend -> production Convex) and builds + uploads the frontend to Cloudflare Pages.
- GitHub Actions secrets:
CONVEX_DEPLOY_KEY,CLOUDFLARE_API_TOKEN,CLOUDFLARE_ACCOUNT_ID,VITE_POSTHOG_PROJECT_API_KEY - GitHub Actions variables:
VITE_POSTHOG_API_HOST,VITE_POSTHOG_UI_HOST - Production Convex environment variables:
JWT_PRIVATE_KEY,JWKS(auth),SITE_URL(the frontend's origin; sign-in links and APIpageUrls point there),API_KEY(read API consumed by the chatpott chatbot),ALERT_EMAIL(receives a mail for every import run ending inwarningorfailed),RESEND_API_KEYandEMAIL_FROM(sign-in links, invitations and alerts; withoutRESEND_API_KEYmails are only logged and nobody can sign in by mail)
The JWT_PRIVATE_KEY / JWKS keypair comes from bun scripts/setup_convex_env.ts (same as local); set SITE_URL and API_KEY yourself.
Analytics (PostHog) is configured via the VITE_POSTHOG_* build-time vars; with no key set, analytics is disabled.