Skip to content

Repository files navigation

Kalender Oberhausen

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

Technology Stack

  • 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/auth with 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

Local Development

bun install
bun run dev

Auth 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.ts

Sign-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.

Commands

  • bun run dev - Vite + Convex dev together
  • bun run build - type-check the frontend, tooling, and Convex backend, then build the production bundle
  • bun run typecheck - TypeScript checks for the frontend, tooling, and Convex backend
  • bun run check:fix - Biome lint + format auto-fix
  • bun 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 again
  • bun 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 invitation
  • bun 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 through auth:signInLink) and hand-entered events
  • bun x convex run integrations/queue:request '{"sources":["<slug>"]}' - queue imports (oberhausen|superhausen|kitev|owt|druckluft; without sources all 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 twice
  • bun x convex run duplicates:detectAll '{"cursor":null}' - rescan every event for duplicate suggestions, e.g. after changing the matching rules in convex/lib/similarity.ts

Embeds

/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, or keine
  • kategorien / ohne-kategorien, einrichtungen / ohne-einrichtungen - restrict the events shown
  • theme - one of the themes in src/themes.ts

Older published forms (layout, ansicht, design, English and earlier German scope names) keep working; src/features/embed/url.ts lists them.

HTTP API

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-separated categoriesAny, categoriesAll, categoriesExclude, institutionsAny, institutionsExclude (at most 10 slugs each). A time word in query (heute, morgen, Wochenende, Freitag, nächste Woche, Dezember, ...; relative to the day of fromMs) narrows the window to its days. Returns { events, total, hasMore, dataHorizon }; each event has id, 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> - optional fromMs, toMs. Returns id, 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.

Deployment

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 API pageUrls point there), API_KEY (read API consumed by the chatpott chatbot), ALERT_EMAIL (receives a mail for every import run ending in warning or failed), RESEND_API_KEY and EMAIL_FROM (sign-in links, invitations and alerts; without RESEND_API_KEY mails 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.