Skip to main content

AMS Frontend

Tech stack: React 18, Vite, TypeScript, TanStack Router, TanStack Query, Shadcn UI, Tailwind, Zustand. GraphQL via Keycloak OIDC auth.

Commands​

  • Dev: pnpm run dev (port 5173)
  • Build: pnpm run build | Lint: pnpm run lint | Codegen: npx graphql-codegen

Key conventions​

  • @/ alias for src/
  • GraphQL: TypedDocumentString from generated types; OIDC token from useAuth().user?.access_token
  • Queries: useGraphQLQuery + centralized keys from src/lib/query-keys.ts
  • Mutations: useGraphQLMutationNew with selector
  • Auth: RequireAuth wraps all routes; authenticated routes under routes/_authenticated/
  • i18n: src/lib/i18n/translations/{en,ja,de}/ — all user-facing text must be translated; use t() hook
  • Error handling: src/lib/handle-server-error.ts; 401 redirects to sign-in

Route structure​

  • Personal workspace: src/routes/_authenticated/p/$workspaceSlug/
  • Org workspace: src/routes/_authenticated/o/$orgSlug/
  • Use getRouteApi('/path/').useParams() — no path duplication
  • Workspace slugs: unique within a user; team slugs: unique within a workspace

Workspace resolution from URL (use-bootstrap.ts)​

  1. /o/.../w/{slug}/... → match by workspace slug
  2. /o/{orgSlug}/... (no /w/) → match by entitySlug — covers org-level admin paths
  3. /p/{slug}/... → match by workspace slug

Step 2 must never be removed — it makes page refresh work on org-level paths without /w/.

Always read docu/docs/domain/navigation.md before modifying sidebar structure, URLs, or groups. Three sidebar types: Staff (org STAFF/MIXED), Client (org CLIENT), Personal. Configuration group (Documents, Templates, Roles & Permissions) is flat.

Build errors vs. warnings​

See docu/docs/ai/claude/rules/frontend-build.md.