Platform

Overview of CyberCTF core services, request flow, and operations.

High-level Architecture

• App Router (Next.js) serving UI and API routes under /app/*
• Authentication via custom OIDC endpoints under /api/oidc/* and session management under /api/auth/*
• Middleware-based route protection in middleware.ts
• Client helpers in lib/client/* and server helpers in lib/server/*
• Shared utilities and i18n under lib/shared/*
• Content-driven docs via Nextra under /docs

Request Flow (Authenticated pages)

1. User hits a protected route like /dashboard.
2. middleware.ts checks cookies and redirects unauthenticated users to / or OIDC authorize flow.
3. In the browser, components use useClientAuth from lib/client-auth.ts to verify session state via /api/auth/session.
4. If tokens are near expiry, /api/auth/refresh attempts a refresh using openid-client.
5. On success, the page renders; otherwise, user is redirected to login.

Auth Endpoints

• GET /api/auth/session → returns { authenticated, needs_refresh, refresh_available } based on cookies
• POST /api/auth/refresh → exchanges refresh token and updates cookie
• GET /api/auth/logout → clears cookies and ends session
• GET /api/oidc/authorize → starts authorization with PKCE
• GET /api/oidc/callback → handles provider callback and sets cookies

See lib/oidc.ts for OIDC client creation and token storage, and app/api/auth/* for route implementations.

Docs System

• Nextra 4 powers the docs under /docs
• Files live in content/ and are mapped via app/docs/[[...mdxPath]]/page.jsx
• Theme-level components are provided by mdx-components.tsx and theme.config.tsx

Ports

• Default dev server: http://localhost:3000 (or next available)
• Public GraphQL (example in code): NEXT_PUBLIC_GRAPHQL_URL

Environment Variables (partial)

• NEXT_PUBLIC_BASE_URL → used for OIDC redirects and fetches
• OIDC issuer/client envs → consumed in lib/oidc.ts

Source Layout

• app/ → routes, pages, API handlers
• components/ → UI components, Shadcn-based primitives in components/ui
• lib/ → client and server helpers, auth, OIDC, store, gql
• content/ → docs content (MDX)
• public/ → static assets

Styling

• Tailwind CSS v4 with @theme tokens in app/globals.css
• @plugin "tailwindcss-animate" for animation utilities
• Dark mode class managed by ThemeProvider