# 00 — Foundation

## 1. High-Level Overview

**Purpose**: Pure leaf modules every other component depends on — TypeScript domain types, framework-agnostic React hooks, and i18next setup. No HTTP, no React tree, no business logic.

**Architectural Pattern**: Foundation / shared kernel.

**Upstream dependencies**: none (intra-repo). External: `i18next`, `react-i18next`, `react`.

**Downstream consumers**: every other `src/` component.

## 2. Internal Interfaces

### `src/types/index.ts`

| Export | Kind | Purpose |
|--------|------|---------|
| `DetectionClass`, `Annotation`, `Affiliation`, `CombatReadiness`, `AnnotationStatus`, `AnnotationSource`, `MediaStatus`, `Flight`, `Waypoint`, `DatasetItem`, `User`, `Permission`, etc. | type / enum | Shared domain shape used by `api/`, providers, and every feature page. |

> **CAVEAT — cross-cutting Step 4 work**. State.json records 4 enum-drift findings against the parent suite spec (`AnnotationStatus`, `Affiliation`, `CombatReadiness`, `MediaStatus`) plus a `Waypoint` shape mismatch. Owner of fix: this single file. The full target shapes live in `_docs/02_document/modules/src__features__annotations.md` findings #27–34 and `src__features__flights.md` finding #20.

### `src/hooks/useDebounce.ts`

| Export | Signature | Purpose |
|--------|-----------|---------|
| `useDebounce<T>(value: T, delay: number): T` | hook | Debounced value mirror. Used by Annotations search and Dataset filters. |

### `src/hooks/useResizablePanel.ts`

| Export | Signature | Purpose |
|--------|-----------|---------|
| `useResizablePanel(initialWidth: number, opts): { width, dragHandleProps }` | hook | Mouse-drag-resizable side panel. Used by Annotations and Dataset pages. Width is **not** persisted (finding #11 in `src__features__annotations.md`). |

### `src/i18n/i18n.ts`

| Export | Kind | Purpose |
|--------|------|---------|
| (default side-effect) | i18next init | Loads `en.json` + `ua.json`, wires `react-i18next`. Imported once by `main.tsx` for its side effect. |

> **CAVEAT**. `lng: 'en'` is hardcoded; no language detector or persistence. `ua.json` exists as a translation target but is not selectable at runtime (finding #1 in `src__i18n__i18n.md`). This is a Step 4 testability/configurability fix.

## 5. Implementation Details

| Module | Notes |
|--------|-------|
| `types/index.ts` | Plain TypeScript. No runtime code. |
| `useDebounce` | `setTimeout` + `clearTimeout` in `useEffect`. |
| `useResizablePanel` | `mousemove` listener attached to `window` while dragging; min/max width clamped. |
| `i18n/i18n.ts` | i18next + ICU plurals. Bundles loaded synchronously (small JSONs, ~100 keys each). |

**State Management**: Stateless apart from the local hook state inside `useDebounce` / `useResizablePanel`. i18next's instance is module-level.

**Key Dependencies**:

| Library | Version | Purpose |
|---------|---------|---------|
| `i18next` | (per `package.json`) | Translation engine |
| `react-i18next` | (per `package.json`) | React bindings; consumed via `useTranslation` in features |
| `react` | 19 | Hooks runtime |

## 7. Caveats & Edge Cases

- Enum drift findings (cross-cutting). See state.json notes 2026-05-10 02:01Z and 02:13Z. Step 4 must reconcile against .NET service before patching `types/index.ts`.
- `i18n` init is synchronous; if either bundle fails to load the app crashes at startup. No fallback.
- `useResizablePanel` does not persist user-chosen width; resets every page nav.

## 8. Dependency Graph

**Must be implemented after**: nothing (Layer 0).

**Can be implemented in parallel with**: itself (the 4 modules are independent).

**Blocks**: every other component in this workspace.

## 6. Extensions and Helpers

`features/annotations/classColors.ts` was originally drafted as part of `06_annotations`, but per the Step 2 BLOCKING gate it has been lifted into its own component, **`11_class-colors`** (sibling shared kernel — see `components/11_class-colors/description.md`). The physical file location is unchanged — only the conceptual ownership moved. The proper physical home (a `src/shared/` or `src/components/detection/` directory) is deferred to Step 2.5 / Step 4 / Step 8.

## Module Inventory

| Path | Module Doc |
|------|------------|
| `src/types/index.ts` | `_docs/02_document/modules/src__types__index.md` |
| `src/hooks/useDebounce.ts` | `_docs/02_document/modules/src__hooks__useDebounce.md` |
| `src/hooks/useResizablePanel.ts` | `_docs/02_document/modules/src__hooks__useResizablePanel.md` |
| `src/i18n/i18n.ts` | `_docs/02_document/modules/src__i18n__i18n.md` |