# Milestone 1 Foundation Audit

This audit maps the funded milestone scope to concrete repository assets and defines the acceptance bar for the foundation. It is intentionally stricter than a scaffold checklist: a future contributor should be able to add machines, scenes, animations, and URL state without editing monolithic viewer code.

## Scope-to-deliverable map

| Scope item | Repository deliverable | Acceptance criteria |
| --- | --- | --- |
| Vite / React / TypeScript scaffold | `package.json`, Vite config, TS configs, `src/main.tsx`, `src/App.tsx`, pages, layout | A clean install can run the declared scripts; routing has catalogue, viewer, and 404 paths. |
| ESLint / Prettier / Tailwind / Zustand setup | Tooling configs, Tailwind config, stores, CSS entry | Styling and state conventions are declared centrally; no lockfile is hand-written. |
| Component architecture document | `docs/component-architecture.md` plus routing, scene, and authoring contracts | UI regions are split into navigation, catalogue, viewer shell, controls, sidebars, overlays, and drawers. |
| Three.js scene architecture | `docs/three-scene-architecture.md`, `src/three/sceneContracts.ts` | Scene adapters receive machine definitions and display state rather than embedding machine-specific logic. |
| Animation interface design | `docs/animation-system.md`, `src/animations/types.ts`, machine animation descriptors | Each machine points at a standard animation module path and exposes RPM, step count, driven parts, and parameters. |
| Machine registry schema | `docs/machine-registry.md`, `src/modules/machines/schema.ts` | Registry entries have stable IDs, categories, difficulty, facts, parts, tours, related machines, asset descriptors, and animation descriptors. |
| Data-driven 28-machine catalogue plan | `src/modules/machines/data/coreMachines.ts`, `registry.ts`, `selectors.ts` | All Phase 1 machines are represented as data with part lists and learning metadata; catalogue logic does not need to know machine internals. |
| URL state model | `docs/url-state-model.md`, `src/utils/urlState.ts`, schema URL types | Shareable state covers machine id, camera, exploded view, hidden parts, opacity, display mode, clipping, annotations, and playback. |
| Accessibility plan | `docs/accessibility-plan.md` | Keyboard navigation, focus, ARIA, reduced motion, contrast, and canvas alternatives are specified. |
| Asset pipeline strategy | `docs/asset-pipeline.md`, asset descriptors in registry | Procedural placeholders and future GLB/KTX2/Draco handoff are represented explicitly. |
| Performance budget | `docs/performance-budget.md`, `src/three/sceneContracts.ts` | Desktop/mobile render quality tiers, pixel ratio caps, particle budgets, and scene budgets are documented. |
| Theme tokens | `tailwind.config.ts`, `src/index.css`, `src/styles/themeTokens.ts` | Premium dark theme colors, spacing, shadows, radii, typography, and motion are centralized. |
| Routing layout | `src/App.tsx`, `src/layouts/AppShell.tsx`, `src/config/routes.ts` | Route generation and parsing are not hardcoded across components. |
| Initial placeholder pages | `src/pages/*`, `src/three/MachinePlaceholderModel.tsx` | Catalogue and viewer can demonstrate the primary navigation path before production GLB assets land. |

## Foundation hardening completed in this pass

The earlier file set established the broad scaffold. This pass closes the main foundation risk: the registry could not remain a single shallow list if the project must scale to 28 core machines and stretch machines. The new registry contract now includes:

- A strict machine schema with compatibility aliases for catalogue components.
- Split data under `src/modules/machines/data/`.
- Complete Phase 1 machine metadata for all 28 required machines.
- Per-machine part descriptions, engineering facts, guided tour steps, related machine IDs, animation descriptors, and asset descriptors.
- Registry validation utilities that catch duplicate IDs, invalid part references, invalid opacity, invalid categories, and broken tour/animation references.
- Route and scene contracts so implementation work can proceed without coupling pages to machine-specific logic.
- Category thumbnail SVGs so catalogue cards have real local assets rather than broken remote placeholders.

## Definition of done for this milestone

Milestone 1 is complete when all of the following are true:

1. The repository contains a runnable Vite/React/TypeScript app shell with routing.
2. The documentation explains component, scene, animation, registry, URL, state, asset, accessibility, deployment, and performance architecture.
3. The Phase 1 catalogue exists as data, not as hardcoded page markup.
4. Adding a new machine requires adding a data entry and optional scene/animation modules, not editing core catalogue or viewer components.
5. Theme tokens and layout constants are centralized.
6. The app can be deployed to Vercel with the documented commands.
7. Known non-final areas are explicitly scoped to later milestones: production GLB assets, machine-specific animation implementations, and final physically detailed procedural/loaded models.

## Non-goals for Milestone 1

The following are intentionally not part of this architecture milestone:

- Final GLB models for every machine.
- Production-grade physics solvers for each mechanism.
- Full mobile interaction polish.
- Final social-preview image generation per machine.
- Complete cross-section shader implementation.

Those items belong to later implementation milestones. The foundation now provides the contracts and data needed to build them without reorganizing the repository.