Frontend architecture

​

Technology

​

Application structure

frontend/src/
├── main.tsx              # Entry point: providers + router mount
├── App.tsx               # Route tree, lazy loading, route guards, error boundaries
├── index.css             # Design tokens, Tailwind, motion vocabulary
├── api                   # (via lib/) fetch wrapper
├── lib/                  # api.ts, auth-client.ts, domain-types.ts, status.ts, money.ts
├── hooks/                # use-auth, use-active-client, use-permissions, use-order-cart, ...
├── components/
│   ├── ui/               # shadcn/ui primitives (Button, Dialog, Table, ...)
│   ├── common/           # ConfirmDialog, SearchInput, DataTableShell, ErrorState, ...
│   ├── layout/           # App shell: navbar, sidebar
│   ├── admin/            # Admin feature components (dialogs, tabs)
│   ├── manager/          # Manager feature components
│   └── orders/           # Shared ordering components
└── pages/
    ├── login.tsx, dashboard.tsx, notifications.tsx, profile.tsx, ...
    ├── admin/            # Muze Admin pages (orders, employees, stores, catalog, ...)
    └── manager/          # Store Manager pages (store, employees, orders, approvals)

​

Bootstrap

<SessionProvider>
  <QueryClientProvider>
    <App />
    <Toaster />
  </QueryClientProvider>
</SessionProvider>

• SessionProvider (better-auth/react) provides useSession() for auth state
• QueryClientProvider provides useQuery() / useMutation() for all API data
• Toaster (sonner) is the toast mount point

​

Routing

const AdminStoresPage = lazy(() => import('@/pages/admin/stores'));
const ManagerOrdersPage = lazy(() => import('@/pages/manager/orders'));

​

Route guards

​

Route groups

​

State management

1. Server state: TanStack React Query (useQuery / useMutation) for all list, detail, and mutation data
2. Auth state: better-auth/react via useSession() and the useAuth() hook
3. Form state: React Hook Form with Zod schemas
4. URL state: React Router’s useSearchParams() and useParams()
5. Local UI state: useState() inside components (modals, toggles, filters)

​

API communication

• Prepends VITE_API_BASE_URL
• Includes credentials: 'include' for session cookies
• Parses error bodies into a typed ApiError with status, message, and optional details
• Redirects to /login?expired=true on 401 responses, with a session-expired toast

​

Component patterns

• UI primitives live in src/components/ui/: shadcn/ui components copied into the repo, not installed as a package
• Feature components are co-located under components/admin/, components/manager/, and components/orders/ next to the pages that use them
• Shared building blocks live in src/components/common/: ConfirmDialog, SearchInput, DataTableShell, TableSkeleton, TablePagination, EmptyState, ErrorState, SelectionBar
• Class merging uses cn() from src/lib/utils.ts (clsx + tailwind-merge)
• Status rendering goes through the central registry in src/lib/status.ts (StatusBadge, StatusIndicator)

​

Build and bundle

​

SEO and metadata

• Per-route document titles. src/hooks/use-document-title.ts sets a unique <title> (and optional meta description and canonical link) per route. Public pages pass a description and canonical; authenticated pages set a title only.
• Static metadata. index.html carries the base title, meta description, Open Graph and Twitter card tags, a canonical link, and Organization/WebSite JSON-LD structured data. The canonical domain is injected at build time from VITE_APP_URL (%VITE_APP_URL%).
• Canonical origin. src/lib/seo.ts reads VITE_APP_URL and exposes APP_URL / absoluteUrl() so pages build absolute links from one source instead of hardcoding the domain.
• robots.txt and sitemap.xml. Vite copies public/ verbatim without env substitution, so these are generated at build time by frontend/scripts/generate-seo-files.cjs into dist/, driven by VITE_APP_URL. robots.txt is permissive and references the sitemap; the sitemap lists only the public pages.

​

External links