key skills

2026-03-10 09:40:07 +01:00
parent ae801428b1
commit 03f452d4d1
19 changed files with 765 additions and 0 deletions
@@ -0,0 +1,94 @@
+# Pascal Editor V2 — Architecture
+
+## Project Structure
+
+Monorepo managed with Turborepo. Packages are shared libraries; apps are deployable applications.
+
+```
+apps/
+  editor/          # Main Next.js app (editor + public routes)
+packages/
+  core/            # Scene schema, state, systems, spatial logic
+  viewer/          # 3D canvas component (React Three Fiber)
+  auth/            # Authentication (better-auth + Supabase)
+  db/              # Database layer (Drizzle ORM + Supabase)
+  ui/              # Shared React UI components
+```
+
+---
+
+## packages/core
+
+Central library — no UI, no rendering. Everything else depends on it.
+
+- **schema/** — TypeScript types for all node types (`Wall`, `Slab`, `Door`, `Item`, etc.)
+- **store/** — Zustand scene store (`useScene`) with undo/redo via Zundo
+- **systems/** — Per-element business logic: geometry generation, constraints (`WallSystem`, `SlabSystem`, `DoorSystem`, …)
+- **events/** — Typed event bus for node changes
+- **hooks/** — `useRegistry` (node ID → THREE.Object3D), `useSpatialGrid` (2D spatial index)
+- **lib/** — Space detection, asset storage, polygon utilities
+
+Node storage is a flat dictionary (`nodes: Record<id, AnyNode>`). Systems are pure logic that runs in the render loop; they read nodes and write back derived geometry.
+
+---
+
+## packages/viewer
+
+3D canvas component — presentation only, no editor concerns.
+
+- **components/viewer/** — Root `<Viewer>` canvas, camera, lights, post-processing, selection manager
+- **components/renderers/** — One renderer per node type (`WallRenderer`, `SlabRenderer`, …), dispatched by `NodeRenderer` → `SceneRenderer`
+- **systems/** — Viewer-specific systems: `LevelSystem` (stacked/exploded/solo), `WallCutout`, `ZoneSystem`, `InteractiveSystem`
+- **store/** — `useViewer`: selection path, camera mode, level mode, wall mode, theme, display toggles
+
+The viewer accepts external props and callbacks (`onSelect`, `onExport`, children) to expose control points. It must not import anything from `apps/editor`.
+
+---
+
+## apps/editor
+
+Next.js 16 app. Composes `@pascal-app/viewer` and `@pascal-app/core` into a full editing experience.
+
+- **app/editor/[projectId]/** — Main editor route
+- **app/viewer/[id]/** — Read-only preview route
+- **store/use-editor.tsx** — `useEditor`: phase (`site | structure | furnish`), mode (`select | edit | delete | build`), active tool
+- **components/tools/** — One component per tool, coordinated by `ToolManager`
+- **components/systems/** — Editor-side systems that integrate with viewer (e.g. space detection for cutaway)
+- **components/editor/** — Camera controls, export, menus, panels
+
+---
+
+## Data Flow
+
+```
+User input (pointer/keyboard)
+  → Tool component (apps/editor/components/tools/)
+  → useScene mutations
+  → Core systems recompute geometry
+  → Renderers re-render THREE meshes
+  → useViewer updates selection/hover
+```
+
+---
+
+## Key Conventions
+
+- **Flat nodes** — All scene nodes live in a single flat record; hierarchy is expressed via `parentId`.
+- **System/renderer split** — Systems own logic; renderers own geometry and material. Never mix.
+- **Viewer isolation** — `@pascal-app/viewer` must remain editor-agnostic. See `viewer-isolation` rule.
+- **Registry pattern** — `useRegistry()` maps node IDs to live THREE objects without tree traversal.
+- **Spatial grid** — 2D grid for fast wall/zone neighborhood queries; avoid brute-force iteration.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| 3D | Three.js (WebGPU), React Three Fiber |
+| Framework | Next.js 16, React 19 |
+| State | Zustand + Zundo |
+| UI | Radix UI, Tailwind CSS 4 |
+| Database | Supabase PostgreSQL + Drizzle ORM |
+| Auth | better-auth |
+| Tooling | Biome, TypeScript 5.9, Turborepo |