Frontend Architecture
The frontend is a React 19 + Vite + TypeScript single-page application with TailwindCSS 4 styling and Shadcn/ui components. Served as static files by nginx.
Core Stack
| Technology | Version | Purpose |
|---|---|---|
| React | 19 | UI framework |
| Vite | — | Build tool, HMR |
| TypeScript | strict | Type safety |
| TailwindCSS | 4 | Utility-first styling |
| Shadcn/ui | (Radix UI) | Accessible component primitives |
| React Router | v7 | Client-side routing |
| TanStack React Query | — | Server state management |
| Zustand | — | Global client state |
| react-hook-form + Zod | — | Form state and validation |
| i18next | — | German/English internationalization |
Directory Structure
| Directory | Files | Purpose |
|---|---|---|
src/pages/ | 96 | Page-level components (one per route) |
src/components/ | 623+ | UI and feature components |
src/components/ui/ | — | Shadcn/ui base components |
src/hooks/ | 43 | Custom React hooks |
src/lib/queries/ | 35 | React Query modules (key factories) |
src/lib/api/ | — | API client functions |
src/lib/ | — | Utilities, helpers, constants |
src/stores/ | — | Zustand stores |
src/locales/ | — | i18n translation files (de/en) |
State Management
Each data type has a designated tool. See State Management for full rules.
| Data Type | Tool | Location |
|---|---|---|
| Server entities (CRUD) | React Query | lib/queries/ |
| Global auth/preferences | Zustand + localStorage | stores/ |
| URL-shareable UI state | URL state hooks | hooks/url-state/ |
| Form fields | react-hook-form + Zod | inline |
| Transient UI | useState | inline |
Component Decomposition
Files exceeding 600 lines must be split. See Component Decomposition for the pattern.
| Module | Contains |
|---|---|
fooService.ts | Pure functions, constants, types (zero React) |
useFooState.ts | State, queries, mutations, handlers |
FooSection.tsx | Presentational (props + useTranslation only) |
Foo.tsx | Orchestrator (calls hook, composes sub-components) |
URL State Hooks
Never use raw useSearchParams. See URL State Management.
| Hook | Purpose |
|---|---|
useTabState | Tab switching with URL sync |
useFilterState | Multi-parameter filter state |
useModalState | Deep-linkable modals/dialogs |
useMultiSortState | Multi-column sort + Shift+Click stacking |
Source: frontend/src/hooks/url-state/
React Query Pattern
All query hooks live in frontend/src/lib/queries/, never inline in components. Uses key factory + as const pattern. ESLint warns on useMutation in components/ or pages/. See React Query Pattern for conventions.
Routing
96 page components mapped via React Router v7. See Routing and Pages Overview for the full route table.
Internationalization
Bilingual (German/English) via i18next. Translation files in src/locales/. LocalizedText type ({de: string, en: string}) used for all database text fields. See Internationalization and Validation Pattern.
Brand Colors
| Name | Value | Hex |
|---|---|---|
| Primary | oklch(75% 0.15 130) | 91C832 |
| Secondary | oklch(44% 0.15 170) | 007C57 |
| Gray-50 | oklch(98.7% 0 0) | F9FAFB |
Related Pages
- Architecture Overview — System-wide architecture
- Component Decomposition — Splitting large components
- Component Library — Shadcn/ui and custom components
- State Management — Data type to tool mapping
- React Query Pattern — Query module conventions
- URL State Management — URL-synced state hooks
- Pages Overview — All 96 pages
- Hooks — Custom hook catalog
- Query Modules — 35 query modules
- Routing — Route configuration
- Internationalization — i18n setup
- API Layer Pattern — Frontend API client structure
- Shared Layer — Types consumed from shared/