);
}
```
### API Client
```typescript
// src/services/api/apiClient.ts — uses Axios instance
import { api } from '@/services/api/apiClient';
// Request interceptors automatically add:
// - Authorization: Bearer {token}
// - X-Tenant-Slug: {currentTenantSlug}
// - Accept-Language: {i18nextLng}
// - X-Correlation-ID: {UUID}
// Usage in service files:
const orders = await api.get('/orders');
const order = await api.post('/orders', { name, amount });
```
### API Service File Pattern
```typescript
// src/services/api/{feature}Api.ts
import { api } from './apiClient';
export interface OrderDto {
id: string;
name: string;
amount: number;
isActive: boolean;
}
export const orderApi = {
getAll: (search?: string) =>
api.get('/orders', { params: { search } }),
getById: (id: string) =>
api.get(`/orders/${id}`),
create: (data: Partial) =>
api.post('/orders', data),
update: (id: string, data: Partial) =>
api.put(`/orders/${id}`, data),
delete: (id: string) =>
api.delete(`/orders/${id}`),
};
```
### Custom Hook Pattern
```typescript
// src/hooks/useOrderDetail.ts
import { useState, useCallback } from 'react';
import { orderApi, OrderDto } from '@/services/api/orderApi';
export function useOrderDetail(id: string) {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const load = useCallback(async () => {
setLoading(true);
setError(null);
try {
const result = await orderApi.getById(id);
setData(result);
} catch (err: unknown) {
setError(err instanceof Error ? err.message : 'Unknown error');
} finally {
setLoading(false);
}
}, [id]);
return { data, loading, error, load };
}
```
### Context Provider Pattern
```typescript
// src/contexts/ExampleContext.tsx
import { createContext, useContext, useState, type ReactNode } from 'react';
interface ExampleContextType {
value: string;
setValue: (v: string) => void;
}
const ExampleContext = createContext(null);
export function ExampleProvider({ children }: { children: ReactNode }) {
const [value, setValue] = useState('');
return (
{children}
);
}
export function useExample() {
const ctx = useContext(ExampleContext);
if (!ctx) throw new Error('useExample must be used within ExampleProvider');
return ctx;
}
```
## UI Styling Patterns
### Semantic Color Usage
| Color | CSS Variables | Usage |
|-------|---------------|-------|
| `blue` | `--info-*` | Totals, informational, in progress |
| `green` | `--success-*` | Completed, resolved, active |
| `yellow` | `--warning-*` | Pending, on hold, warnings |
| `red` | `--error-*` | Errors, critical, failed |
| `neutral` | `--bg-secondary`, `--text-primary` | Inactive, closed, disabled |
---
## Commands
```bash
# Development
npm run dev # Start dev server (port 6173)
# Build
npm run build # Production build
# Tests (MANDATORY before commit)
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
# Lint
npm run lint # ESLint check
npm run typecheck # TypeScript type check
```
## Routing
### Lazy Loading
All non-critical pages use `React.lazy()` for code splitting:
```tsx
const OrdersPage = lazy(() =>
import('@/pages/{module}/OrdersPage').then(m => ({ default: m.OrdersPage }))
);
```
### Route Guards (Layered)
```
Auth check → Tenant transition → Permission check → Render
```
---
## App chrome comes from the package — including the mobile shell
`@atlashub/smartstack` renders the application chrome around ``.
**Never build a local `AppShell` / `Sidebar`**: a second chrome inside the
package's is a permanent drift source, and it will not carry any of the mobile
behaviour below.
| Viewport | Rendered by the package |
|---|---|
| Desktop | App header, hierarchical sidebar (nav read from `/api/navigation/menu`), tenant switcher, user menu, content outlet. |
| Mobile | The "descente par paliers" shell: Applications → Modules → Sections → the resource page, a header with hierarchical back + breadcrumbs, the tenant chip + sheet, transverse search, offline banner + outbox sheet, and "Reprendre" cards. |
The mobile shell is driven by the **transverse bottom bar** — four fixed
entries, always present whatever the palier:
| Tab | What it shows |
|---|---|
| **Applications** | The palier navigation root (this app's DB menu). |
| **Tâches** | `GET /api/me/tasks` — every queue the caller owns, across modules. |
| **Activité** | `GET /api/me/activity` — the caller's recent events. |
| **Compte** | Profile, tenant, language, theme, sign-out. |
Both aggregates already carry the platform queues. To merge this app's own
entities into them, register from the Infrastructure DI (backend):
`AddExtensionTasks(tasks => tasks.Entity(…)…)` —
declarative, the mirror of `AddExtensionSearch` — or a hand-written
`ITaskProvider` / `IActivityProvider` via `AddSmartStackTaskProvider()` /
`AddSmartStackActivityProvider()`. **Nothing to write on the frontend.**
**The shell is ON by default** — nothing to turn on. The optional
`` block (written by `/pwa`)
makes the choice explicit and is the only way to set `breakpoint`,
`shellComponent` or `bottomNav`; `enabled: false` opts out entirely.
What decides whether one of YOUR pages shows up inside the shell is its
`PageMobileMeta` — the third argument of `PageRegistry.register`, emitted from
the page's `pwa.support`. A page with no mobile metadata is desktop-only and is
hidden from the mobile menu. The palier navigation itself is the app's own DB
menu; there is no mobile-specific navigation model to author.
---
## Rules
1. **CRITICAL: i18n Required** - ALL pages must use `useTranslation()` with all 4 language files (fr/en/it/de)
2. **Pages in `pages/`**, components in `components/`** - organized by application/module
3. **Custom hooks for logic** - extract API calls and state management from components into `hooks/`
4. **Context API for global state** - use `contexts/` for auth, tenant, navigation, theme, etc.
5. **Axios API client** - all HTTP calls via `services/api/apiClient.ts`, never raw `fetch()`
6. **TypeScript strict mode** - no `any` types
7. **Tailwind for styling** - no CSS files, no inline styles (`style={{}}`)
8. **Functional components only** - no class components
9. **Composition over inheritance** - use props and children
10. **Tests in `tests/`** - NOT in `src/`, use Vitest + Testing Library
## CRITICAL: Tabs Must Persist in URL
When creating a page with tabs, **ALWAYS** persist the active tab in the URL query params (`?tab=xxx`).
Use the `useTabNavigation` hook.
## When Adding New Feature
1. Create page in `pages/{application}/{module}/`
2. Create components in `components/{feature}/`
3. Create API service in `services/api/{feature}Api.ts`
4. Create custom hooks in `hooks/use{Feature}.ts`
5. Register page via `PageRegistry.register()`
6. **CRITICAL**: Add translations to ALL 4 locales: `i18n/locales/{fr,en,it,de}/`