Web application

Facts verified 2026-07-30 by claude-code/2026.07. Generated from the authored source at docs/llm-wiki/web-application.md — the wiki owns these facts (ADR: D1 of docs/plans/20260811_documentation_system_execution.md). Edit that file, then regenerate: python docs/portfolio/_build/generate_wiki_pages.py.

Stack

  • Next.js 15 (App Router) + React 18, TypeScript, at web/ (repo root).
  • Styling: Tailwind CSS + shadcn/ui. State: React contexts and hooks — no Redux.
  • Auth & database: Supabase (session cookies, checked in web/middleware.ts).
  • 3D/viewers: CesiumJS (gallery, photo-map-3d, gas-heatmap modules), Autodesk APS (CAD).
  • Tests: Vitest (web/vitest.config.ts, web/vitest.components.config.ts) + Playwright (web/playwright.config.ts).

Folder map (web/)

  • app/ — routes; folder tree = URL structure. Route groups: (public) (landing, login, signup) and (authenticated) (the product). Workspaces live at app/(authenticated)/w/.
  • app/api/ — the app’s own backend: ~97 route handlers (see backend-api.md).
  • middleware.ts — runs before every request: Supabase session refresh + workspace redirects.
  • components/ — reusable UI (see components.md).
  • modules/ — six self-contained feature modules: gallery, photo-map-3d, gas-heatmap, thermal-pair-viewer, cad-viewer, dataset-onboarding. Each has internal core/ ui/ shared/ services/ overlays/ and a single index.ts entry.
  • lib/ — shared non-UI logic: supabase/ (browser/server/admin clients), ag-ui/, chat/, workspaces/ (module registry), cloud-storage.ts, jwt.ts, database.generated.ts.
  • hooks/ — 17 shared use-* hooks (AG-UI client/events, auth token, chat history, network status …).
  • providers/ — global contexts: SessionProvider, OrganizationProvider, theme. Wrapped around every page by app/layout.tsx.
  • public/ — served verbatim; includes the Swagger spec at public/api-docs/swagger.yaml.

Request flow

  • Browser → middleware.ts → server component (app/) or API route handler (app/api/).
  • Route handlers front: Supabase (auth, Postgres + RLS, storage), the AI Gateway (SSE chat), Azure Blob/GCS media, Autodesk APS, Google Cloud Text-to-Speech.
  • Two deliberate bypasses of the API layer: the Supabase browser client (lib/supabase/client.ts, auth session) and Cesium Ion 3D-tile streaming to the modules.
  • Architecture diagram: docs/handbooks/static/assets/web-architecture.excalidraw.svg (editable Excalidraw scene embedded).

Authoritative sources

docs/handbooks/content/web/index.md · docs/handbooks/content/web/folder-structure.md · docs/handbooks/content/web/what-is-a-web-application.md