- Read-only role: /admin/me's permissions decide via canEditCalendar (lib/permissions.ts, mirrors the API's canWrite: only `access` writes). Read-only accounts see everything but get no "Neuer Termin", no "+", no "Veröffentlichen"; an event opens as "Termin ansehen" with locked fields. A "Nur lesen" badge in the header explains why. The API refuses their writes regardless. - The management calendar is labelled "Vorstand"; the slug stays `management` for the API, URLs and iCal links. - The subscription dialog's Apple/Google links are plain anchors styled with buttonVariants instead of Base UI Buttons rendering an <a>, which warned in dev and would have given them role="button". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.0 KiB
Architecture
Next.js 16 (App Router) + React 19 + TypeScript + Tailwind 4 + shadcn (preset b7ClO5que, Base UI
primitives) - the same stack as nachklang-feedback. Rewritten from Angular in September 2026; the
decisions behind it are in rewrite-plan.md.
Routes
| Path | What | Rendering |
|---|---|---|
/ |
Public landing page: subscribe links + next public events | Server component, static, revalidate = 300 |
/admin |
Event management (list + edit sheet) | Client, behind proxy.ts and the /me gate |
/admin/login |
Forwarder to the admin app's login | Client |
Authentication
This app has no login and no credential of its own. The session is an httpOnly cookie
(__Secure-nachklang.session_token in production, nachklang.session_token over http in dev) that
the API sets on .nachklang.art; it is shared by calendar, feedback, tickets and admin.
proxy.ts- a convenience gate on/admin/*: no session cookie →/admin/login?redirect=…. It only sees the cookie's presence, never its validity.app/admin/login/page.tsxforwards to${NEXT_PUBLIC_ADMIN_APP_URL}/login?redirect=<absolute URL>.app/admin/layout.tsxcallsGET /admin/meand decides:- 401 → login (the only status that redirects);
- 403, or 200 without
"calendar"inapps→ "Kein Zugriff" (no redirect: it would loop); - anything else (5xx, network, CORS = status 0) → "nicht erreichbar" (no redirect).
- Every API call uses
credentials: "include"(lib/api.ts). Without it the browser sends no cookie and the API answers 401. - Any 401 later (session ended in another app) → toast + login with this page as return target.
GET /admin/me answers 200 for an account without the calendar permission; only apps shows
it. The layout's apps.includes("calendar") check is load-bearing.
Read-only role. /admin/me also returns permissions: [{app, role}]. lib/permissions.ts
(canEditCalendar) mirrors the API's canWrite: only a calendar grant with role access may
change anything; read - or any role the app doesn't know - is read-only. Without permissions
(an API from before the role) it falls back to apps. The UI reads it through useCanEdit()
(AdminSession.tsx) and hides every write control; EventSheet turns into a view. Enforcement
is the API's: requireAppAccess refuses non-GET requests from read grants with 403. See the
API's docs/admin-roles.md.
Data flow (admin)
components/admin/useEvents.tsloads all five calendars in parallel fromGET /calendar/events/{slug}/json(there is no all-in-one endpoint). Each calendar loads and fails on its own; a per-calendar request counter drops stale responses. Deleted events (the admin feed returns them) are dropped byparseApiEvent.- Filtering, sorting and month grouping are client-side (
lib/filter.ts); nothing is re-fetched when a filter changes. The view state lives in the URL (lib/url-state.ts,useListState):?cal=public,choir&range=past&sort=start_desc&q=probe, defaults omitted. The default sort depends on the range (Vergangen= newest first). - Writes (
components/admin/EventSheet.tsx):- validate (
validateEventForm) → focus the first invalid field, no request; - new →
POST /calendar/events; - edit →
PUT /calendar/events/move/:idif the calendar changed, thenPUT /calendar/events/:idonly if anything else changed (contentChanged); - the sheet closes only after the API answered; a failure keeps the edits and shows the reason.
- After a save the list updates at once (
eventFromPayload), then the affected calendars are re-fetched for server-side fields.
- validate (
- PUT replaces the whole event and defaults missing fields (
status ?? 'PUBLIC',repeatFrequency ?? ''). Every write sends the completeEventPayload- including the quick "Veröffentlichen", which usespayloadFromEvent.
Time
All wall-clock times mean Europe/Berlin, whatever the browser's zone (lib/dates.ts,
@date-fns/tz). Forms hold "YYYY-MM-DD" / "HH:mm" strings; the API gets UTC ISO instants.
- Whole-day events are stored as 00:00 on the first day to 23:59 on the last (inclusive), Berlin. The API's iCal export treats the end date as inclusive and adds a day.
- Repeating events (any
repeatFrequency) count as current and sort by their next occurrence (nextOccurrence); a 29 February birthday falls on 28 February in common years. - Vitest runs with
TZ=America/New_Yorkso Berlin handling can't pass by accident.
Calendars
lib/calendars.ts is the single list: id, slug, German label, colours, default visibility and a
forced recurrence (Birthdays → YEARLY). It mirrors calendarNames in the API's
events.router.ts; a new calendar needs an entry in both.
Public landing page
app/page.tsx fetches GET /calendar/events/public/json on the server (lib/public-calendar.ts,
next: { revalidate: 300 }), anonymously. On any failure the events section is simply left out;
the subscribe links never depend on the API. Links from the database are only rendered if they pass
normaliseUrl (http/https) - old rows were never validated.
Subscription URLs for the internal calendars carry the shared password and come from
GET /calendar/events/subscriptions (editors only), shown in SubscriptionsDialog.
Configuration
| Variable | When | Purpose |
|---|---|---|
NEXT_PUBLIC_API_BASE_URL |
build time (inlined) | API origin for the browser and the subscribe links |
NEXT_PUBLIC_ADMIN_APP_URL |
build time (inlined) | Where signing in happens |
API_BASE_URL |
runtime, optional | Server-side fetch of the landing page's events; may be internal |
lib/env.ts throws on a missing NEXT_PUBLIC_* value, so a misconfigured build fails instead of
shipping localhost URLs.
Tests
npm test - Vitest over the pure logic in lib/ (dates, form rules, filtering, URL state, parsing,
API client with a stubbed fetch, landing page selection). Components are checked in the browser,
not unit-tested (decision Q10).