Architecture
Frontend architecture
Actor-specific applications, feature boundaries, shared packages, server safety, and testing contracts.
The frontend is a pnpm/Turborepo monorepo with three actor-specific React applications.
| Application | Actor | Runtime |
|---|---|---|
| Back-office | Administrator | TanStack Start SSR |
| Supervision | Operator | Vite SPA |
| Counter | Ticket agent | Vite SPA; future Tauri shell |
Feature-first structure
Features mirror backend modules and use the same glossary. Routes resolve URL state and render; they do not own business rules or call raw adapters.
apps/<app>/src/features/<feature>/
├── domain or model/ pure rules and view contracts
├── application/ orchestration and ports
├── adapters/ server or browser integrations
├── ui/ feature components
└── public facades audience-specific exportsShared package platform
| Package | Responsibility |
|---|---|
@smartgare/ui | Semantic tokens and owned shadcn/ui source |
@smartgare/api | HTTP client and generated backend types |
@smartgare/auth | Browser OIDC adapter |
@smartgare/realtime | SSE subscriptions |
@smartgare/offline | Counter outbox and storage ports |
@smartgare/i18n | French-primary catalog and future Arabic/RTL |
@smartgare/testing | Vitest, MSW, render helpers, and fakes |
Client/server safety
The back-office is a backend-for-frontend. Bearer and refresh tokens stay in the HTTP-only server session. Browser routes call authenticated server functions. Server configuration and raw adapters cannot enter the client bundle.
Supervision and counter use browser OIDC through @smartgare/auth. All three
applications use backend capabilities for UI affordances while relying on the
backend for enforcement.
Testing contract
- Tests live beside feature code.
- MSW handles HTTP and refuses unmocked requests.
- UI tests query roles and labels rather than implementation IDs.
- E2E runs against explicit mock-mode production builds.
- Required API fields are validated before a server route exposes data to the browser.