# Repository Structure

This scaffold follows the requested Mechanica architecture while keeping each layer focused.

```text
.
├── docs/
├── public/
├── src/
│   ├── animations/
│   ├── assets/
│   ├── components/
│   │   ├── catalogue/
│   │   ├── navigation/
│   │   ├── ui/
│   │   └── viewer/
│   ├── config/
│   ├── hooks/
│   ├── layouts/
│   ├── modules/
│   │   └── machines/
│   ├── pages/
│   ├── shaders/
│   ├── store/
│   ├── three/
│   ├── types/
│   └── utils/
├── index.html
├── package.json
├── tailwind.config.ts
├── tsconfig.json
├── vite.config.ts
└── vercel.json
```

## Directory responsibilities

### `docs`

Technical planning package for funded milestone one.

### `public`

Static assets served directly by Vite/Vercel. Production GLB files, thumbnails, and decoder files should be placed under `public/assets` or served from a CDN configured through `VITE_ASSET_BASE_URL`.

### `src/animations`

Animation interfaces and future machine-specific animation modules.

### `src/assets`

Source-side asset documentation and future lightweight imported assets. Heavy runtime assets should usually live in `public/assets`.

### `src/components`

Reusable React components grouped by product region.

### `src/config`

Environment normalization. All environment reads should be centralized here instead of scattering `import.meta.env` throughout the app.

### `src/hooks`

Reusable React hooks that are not Zustand stores.

### `src/layouts`

Route shells and persistent chrome.

### `src/modules`

Domain modules. The machine registry lives here because it is domain data, not UI.

### `src/pages`

Route-level screens.

### `src/shaders`

Custom shader source and shader documentation. Empty until a rendering feature requires GLSL.

### `src/store`

Zustand stores.

### `src/three`

React Three Fiber scene, controls, materials, model adapters, and camera presets.

### `src/types`

Shared types used across stores, utilities, and rendering.

### `src/utils`

Framework-independent helpers.

## Naming conventions

- React components: `PascalCase.tsx`
- Hooks: `useThing.ts`
- Stores: `thingStore.ts`
- Domain schema files: `schema.ts`
- Registry data: `registry.ts`
- Selectors: `selectors.ts`
- Part IDs: kebab-case
- Machine IDs: kebab-case
- Route slugs: kebab-case

## Import conventions

Prefer explicit relative imports inside the scaffold. Path aliases can be added later if the module graph grows enough to justify them.

## Files intentionally not committed

- `node_modules`
- `dist`
- local `.env` files
- generated lockfile until maintainers run package-manager resolution
- generated optimized GLB derivatives until the asset pipeline is active