#Salon Admin UI — Quickstart

Salon Admin UI (salon-admin-ui) is the internal operations console for the Auralynk AI salon platform. It is a single-page React application used by internal operators to manage salon stores, monitor device health, review diagnostics, work a tasks queue, and administer operator accounts and RBAC roles.

Version: 2.2.1 | Deploy targets: console.auralynkai.com (prod) · console-uat.auralynkai.com (UAT)
Source: src/ | Template origin: shadcn-admin (adapted)

#What the app does

#Tech stack

#Getting started

Prerequisites: Node.js with npm. (A pnpm-lock.yaml lingers from the original template but npm is used exclusively.)

# 1. Install dependencies
npm install

# 2. Configure environment (copy .env.example → .env.local, set API URLs)
cp .env.example .env.local

# 3. Start dev server (points at localhost:8080 backend by default)
npm run dev

# 4. Or start against UAT backend
npm run dev:uat

The app runs at http://localhost:5173 by default.

#Environment variables

These are the only two env vars. All .env.* files are committed — they contain only public endpoint URLs, no secrets. Use .env.local (gitignored) to override on your machine. See src/lib/config.ts for how they're used.

#Available scripts

npm run dev          # Dev server, local backend
npm run dev:uat      # Dev server, UAT backend
npm run build        # TypeScript check + Vite production build
npm run build:uat    # TypeScript check + Vite UAT build
npm run deploy       # build + wrangler deploy (production)
npm run deploy:uat   # build:uat + wrangler deploy --env uat
npm test             # Vitest unit/integration tests (JSDOM)
npm run test:watch   # Vitest in watch mode
npm run lint         # ESLint (no-console is an error)
npm run format       # Prettier write
npm run knip         # Find unused files/exports/deps

#Project layout

src/
├── main.tsx               # App entry point — provider stack + router
├── routes/                # TanStack Router file-based route definitions
│   ├── __root.tsx         # Root layout (Toaster, devtools, query context)
│   ├── _authenticated/    # Protected routes (auth gate, main app layout)
│   └── (auth)/            # Login/OTP pages (no auth required)
├── features/              # Business feature modules (one dir per feature)
├── components/            # Shared components (data-table, layout, UI primitives)
├── auth/                  # Auth context, API calls, RequireAuth, RequirePermission
├── lib/                   # Core infrastructure (httpClient, tokenStore, queryClient, config)
├── stores/                # Zustand stores (legacy — one store, not active)
├── context/               # UI preference contexts (theme, font, direction, layout)
├── hooks/                 # Shared hooks (useTableUrlState)
├── config/                # Static config (font names)
└── test/                  # All tests (mirrors src/ structure)

#Documentation sections

• Architecture — App boot, routing, auth flow end-to-end, HTTP client, shared infrastructure, contexts, deploy
• Features — Every business feature module: what it shows, what APIs it calls, key types, UI patterns
• Testing — Test structure, utilities, mocking approach, what's covered, how to run

#Key conventions for agents

• Add a new feature: Create src/features/<name>/ with types.ts, api.ts, components, and tests in src/test/features/<name>/. Add a route file in src/routes/_authenticated/. Wire nav in src/components/layout/data/sidebar-data.ts with a permission guard.
• Add a new API call: Use apiFetch<T>() from src/lib/httpClient.ts. Never use raw fetch for authenticated calls.
• Add a permission gate: Use <RequirePermission permission="resource.action"> or the can() helper from useAuth(). The permission string must also be added to the server-side permission catalog.
• Table with URL-synced filters: Use useTableUrlState from src/hooks/ and the DataTable* components from src/components/data-table/.
• Do not add secrets to .env.* files — all env files are committed.
• Run npm test and npm run lint after any change. CI is not yet configured; manual verification is required before deploy.