Skip to main content

Frontend Architecture

The Qarion frontend is a modern Single Page Application (SPA) built with React, leveraging a custom design system and standard enterprise patterns.

Tech Stack​

  • Framework: React 18+
  • Build Tool: Vite (for fast HMR and optimized builds)
  • State Management: Context API (for global state like Auth, Theme) and React Query (for server state).
  • Routing: React Router DOM.
  • Styling: CSS Modules / Custom "Glass UI" System.
  • Internationalization: react-i18next with browser language detection (en, fr, de, es).

Design System: Glass UI​

We utilize a bespoke design system known as "Glass UI," focusing on:

  • Translucency: Frosted glass effects for depth and hierarchy.
  • Vibrant Colors: HSL-based color palettes that support theming.
  • Micro-interactions: Subtle animations for feedback.
  • Dark Mode First: The UI is optimized for dark mode but fully supports light mode.

Visual Standards​

  • Standard #330-CardInternal: Rules for internal spacing within cards to prevent visual clutter.
  • Badges: High-density badge hierarchy for status indicators.

Architecture Patterns​

Component Structure​

Components are organized by domain (e.g., components/Jobs, pages/Admin) rather than by technical type (e.g., components/atoms, components/molecules).

Data Fetching​

We strictly use TanStack Query (React Query) for data fetching.

  • Caching: Automatic caching and invalidation of server data.
  • Loading States: Unified handling of isLoading and isError.
  • Optimistic Updates: Immediate UI feedback for actions like "Star Item" or "Delete".

Custom Hooks​

We employ specialized custom hooks for complex logic:

  • Pagination: useResultPagination handles client-side pagination state for large dataset views (e.g., Query Editor results), abstracting away page size limit, offsets, and chunking logic.

The application makes heavy use of tabbed interfaces (e.g., Product Pages, Admin Settings).

  • Persistence: Tab selection is often synchronized with the URL hash or query parameters to support deep linking and browser history.
  • Lazy Loading: Tab content is loaded only when the tab is active, reducing initial bundle size and load time.

Internationalization (i18n)​

All user-facing strings are externalized into JSON translation files and loaded via react-i18next.

  • Entry point: frontend/src/i18n.js initializes i18next with bundled translations and i18next-browser-languagedetector.
  • Hook: Components use the useT(namespace) hook (frontend/src/hooks/useT.js) — a thin wrapper around useTranslation that binds a namespace, e.g. useT('settings').
  • Formatting: The useFormatters hook (frontend/src/hooks/useFormatters.js) provides locale-aware number, date, and percentage formatting.
  • Translation files: One JSON file per locale in frontend/public/locales/{en,fr,de,es}/translation.json, organized into ~65 namespaces.
  • Adding translations: Add keys to all four locale files under the appropriate namespace. The namespace should match the page or component area.

Workstations​

"Workstations" are specialized, high-density interfaces for specific power-user tasks.

  • Quality Check Detail: A specialized view for analyzing quality metrics and history.
  • Issue Triage: Kanban-style board for managing data issues.

These workstations often implement their own local state management and optimized rendering logic for handling large datasets.