# Mechanica — Mechanical Systems Explorer

Mechanica is a Vite + React + TypeScript foundation for a premium dark-themed mechanical systems explorer. This milestone establishes the repository architecture, data-driven machine registry, URL state model, viewer shell, theme tokens, lint/format/build tooling, and planning documents needed to scale to the 28-machine core catalogue without monolithic files.

## Quickstart

```bash
npm install
cp .env.example .env.local
npm run dev
```

Open the local URL printed by Vite. The catalogue is available at `/`, and machine routes use `/machines/:slug`, for example:

```text
/machines/four-stroke-petrol-engine
```

## Verification commands

```bash
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run preview
```

No lockfile is committed in this scaffold. Generate one on the first install with your package manager and commit the generated lockfile after dependency resolution is verified on the target environment.

## Project structure

```text
src/
├── animations/         Standard animation interface contracts
├── assets/             Asset pipeline landing area and conventions
├── components/         Reusable UI, catalogue, navigation, and viewer panels
├── config/             Environment variable normalization
├── hooks/              Route/search/FPS hooks
├── layouts/            Application chrome and route outlet
├── modules/            Domain modules, starting with the machine registry
├── pages/              Route-level pages
├── shaders/            Shader conventions and future custom GLSL modules
├── store/              Zustand stores
├── three/              React Three Fiber scene composition
├── types/              Shared TypeScript primitives
└── utils/              Framework-independent helpers
```

## Documentation package

- [Component architecture](docs/component-architecture.md)
- [Three.js scene architecture](docs/three-scene-architecture.md)
- [Animation system architecture](docs/animation-system.md)
- [Machine registry format](docs/machine-registry.md)
- [URL state model](docs/url-state-model.md)
- [Accessibility plan](docs/accessibility-plan.md)
- [Asset pipeline and loading strategy](docs/asset-pipeline.md)
- [State management](docs/state-management.md)
- [Deployment on Vercel](docs/deployment-vercel.md)
- [Performance budget and optimization report](docs/performance-budget.md)
- [Repository structure](docs/repository-structure.md)

## Current milestone notes

The 3D scene currently renders a procedural, data-driven engineering preview for each machine so routing, panels, picking, annotations, exploded view controls, clipping controls, and share URL encoding have a working path before production GLB assets arrive. The registry already contains all 28 Phase 1 machines with metadata, facts, parts, guided-tour steps, animation profile metadata, and related-machine links.
