# protogulix/pantin architecture

> Architecture diagram of the GitHub repository protogulix/pantin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/protogulix/pantin
- Repository: https://github.com/protogulix/pantin

## Overview

Pantin is a browser-based editor for mechanical assemblies, with a core service and CLI supporting the same project data. The main workflow is to open or import a Pantin, organize bodies into assemblies, edit joints and tags, and inspect or manipulate the resulting 3D pose. The graph also includes STEP conversion, simulation, and persistent project storage. Some relationships are supported only by the SOURCE INDEX or documented capability names; uncertain integration links are omitted rather than inferred.

Main entry points: [`packages/core/src/service/pantin-service.ts`](https://github.com/protogulix/pantin/blob/master/packages/core/src/service/pantin-service.ts) (Pantin service), [`packages/core/src/http/routes.ts`](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/routes.ts) (HTTP route dispatch), [`packages/viewer/src/main.ts`](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/main.ts) (Viewer application), [`packages/viewer/src/controller/controller.ts`](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/controller/controller.ts) (Editor controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_viewer["Browser editor"]
  node_viewerapp["Viewer application<br/>[main.ts]"]
  node_controller["Editor controller<br/>[controller.ts]"]
  node_viewerstate["Editor state<br/>[viewer-state.ts]"]
  node_treestate["Tree state and IDs<br/>[tree-state.ts]"]
  node_assemblydisplay["Assembly display"]
  node_jointform["Joint editor<br/>[joint-form.ts]"]
  node_viewport["3D viewport<br/>[viewport.ts]"]
  node_viewmodel["View model<br/>[view-model.ts]"]
  node_translations["Translations<br/>[translate.ts]"]
  node_messages["Editor messages<br/>[messages.ts]"]
end

subgraph group_api["API and contract"]
  node_client["API client<br/>[api-client.ts]"]
  node_transport["API transport<br/>[api-transport.ts]"]
  node_protocol["Shared API contract<br/>[api.ts]"]
  node_server["HTTP server<br/>[server.ts]"]
  node_routes["HTTP route dispatch<br/>[routes.ts]"]
  node_assemblies["Assembly routes<br/>[assembly-routes.ts]"]
  node_joints["Joint and pose routes<br/>[joint-routes.ts]"]
  node_requestread["Request decoding<br/>[request-reading.ts]"]
  node_responses["API responses<br/>[responses.ts]"]
  node_routecontext["Route context<br/>[route-context.ts]"]
end

subgraph group_core["Core domain"]
  node_validation["Input validation<br/>[validation.ts]"]
  node_service["Pantin service<br/>[pantin-service.ts]"]
  node_domain["Assembly and joint model"]
  node_simulation["Pose simulation<br/>[simulation.ts]"]
  node_poseevents["Pose stream"]
end

subgraph group_conversion["Import conversion"]
  node_converter["STEP converter<br/>[step-converter.ts]"]
  node_stepworker["STEP conversion engine<br/>[conversion.py]"]
end

subgraph group_runtime["Persistence and runtime"]
  node_cli["Folder validation CLI<br/>[validate-folder.ts]"]
  node_store[("Pantin file store<br/>[pantin-store.ts]")]
end

node_user(("Editor user"))
node_cliuser(("CLI user"))

node_user -->|"uses"| node_viewerapp
node_viewerapp -->|"wires intents"| node_controller
node_controller -->|"updates"| node_viewerstate
node_controller -->|"selects nodes"| node_treestate
node_controller -.->|"requests actions"| node_client
node_viewerapp -->|"creates view"| node_viewport
node_viewerapp -->|"renders model"| node_viewmodel
node_viewerstate -->|"checks nodes"| node_treestate
node_viewerstate -->|"tracks display"| node_assemblydisplay
node_viewerstate -->|"stores form"| node_jointform
node_viewerapp -->|"loads language"| node_translations
node_viewerapp -->|"shows messages"| node_messages
node_client -->|"sends requests"| node_transport
node_transport -->|"validates payloads"| node_protocol
node_server -->|"dispatches requests"| node_routes
node_routes -->|"registers routes"| node_assemblies
node_routes -->|"registers routes"| node_joints
node_routes -->|"decodes requests"| node_requestread
node_routes -->|"sends responses"| node_responses
node_routes -->|"builds context"| node_routecontext
node_assemblies -->|"calls operations"| node_service
node_joints -->|"calls operations"| node_service
node_assemblies -->|"validates input"| node_validation
node_joints -->|"validates input"| node_validation
node_routecontext -->|"types service"| node_service
node_service -->|"reads and writes"| node_store
node_service -->|"delegates operations"| node_domain
node_service -.->|"imports bodies"| node_converter
node_service -->|"runs steps"| node_simulation
node_routes -->|"registers stream"| node_poseevents
node_poseevents -->|"uses context"| node_routecontext
node_converter -.->|"invokes converter"| node_stepworker
node_cliuser -->|"runs validation"| node_cli
node_cli -->|"checks projects"| node_service

click node_viewerapp "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/main.ts"
click node_controller "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/controller/controller.ts"
click node_viewerstate "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/viewer-state.ts"
click node_treestate "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/tree/tree-state.ts"
click node_assemblydisplay "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/assembly-display.ts"
click node_jointform "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/joints/joint-form.ts"
click node_viewport "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/scene/viewport.ts"
click node_viewmodel "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/view-model.ts"
click node_translations "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/i18n/translate.ts"
click node_messages "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/messages.ts"
click node_client "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/api-client.ts"
click node_transport "https://github.com/protogulix/pantin/blob/master/packages/viewer/src/api-transport.ts"
click node_protocol "https://github.com/protogulix/pantin/blob/master/packages/protocol/src/api.ts"
click node_server "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/server.ts"
click node_routes "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/routes.ts"
click node_assemblies "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/assembly-routes.ts"
click node_joints "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/joint-routes.ts"
click node_requestread "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/request-reading.ts"
click node_responses "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/responses.ts"
click node_routecontext "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/route-context.ts"
click node_validation "https://github.com/protogulix/pantin/blob/master/packages/core/src/domain/validation.ts"
click node_service "https://github.com/protogulix/pantin/blob/master/packages/core/src/service/pantin-service.ts"
click node_domain "https://github.com/protogulix/pantin/tree/master/packages/core/src/domain"
click node_simulation "https://github.com/protogulix/pantin/blob/master/packages/core/src/service/simulation.ts"
click node_poseevents "https://github.com/protogulix/pantin/blob/master/packages/core/src/http/pose-stream-routes.ts"
click node_converter "https://github.com/protogulix/pantin/blob/master/packages/core/src/converter/step-converter.ts"
click node_stepworker "https://github.com/protogulix/pantin/blob/master/packages/step-converter/src/pantin_step_converter/conversion.py"
click node_cli "https://github.com/protogulix/pantin/blob/master/packages/cli/src/validate-folder.ts"
click node_store "https://github.com/protogulix/pantin/blob/master/packages/core/src/store/pantin-store.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_viewerapp,node_controller,node_viewerstate,node_treestate,node_assemblydisplay,node_jointform,node_viewport,node_viewmodel,node_translations,node_messages,node_user,node_cliuser toneBlue
class node_client,node_transport,node_protocol,node_server,node_routes,node_assemblies,node_joints,node_requestread,node_responses,node_routecontext toneAmber
class node_validation,node_service,node_domain,node_simulation,node_poseevents toneMint
class node_converter,node_stepworker toneRose
class node_cli,node_store toneIndigo
```

## Components

### Browser editor

- [Viewer application](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/main.ts): `packages/viewer/src/main.ts`
- [Editor controller](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/controller/controller.ts): `packages/viewer/src/controller/controller.ts`
- [Editor state](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/viewer-state.ts): `packages/viewer/src/viewer-state.ts`
- [Tree state and IDs](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/tree/tree-state.ts): `packages/viewer/src/tree/tree-state.ts`
- [Assembly display](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/assembly-display.ts): `packages/viewer/src/assembly-display.ts`
- [Joint editor](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/joints/joint-form.ts): `packages/viewer/src/joints/joint-form.ts`
- [3D viewport](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/scene/viewport.ts): `packages/viewer/src/scene/viewport.ts`
- [View model](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/view-model.ts): `packages/viewer/src/view-model.ts`
- [Translations](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/i18n/translate.ts): `packages/viewer/src/i18n/translate.ts`
- [Editor messages](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/messages.ts): `packages/viewer/src/messages.ts`

### API and contract

- [API client](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/api-client.ts): `packages/viewer/src/api-client.ts`
- [API transport](https://github.com/protogulix/pantin/blob/master/packages/viewer/src/api-transport.ts): `packages/viewer/src/api-transport.ts`
- [Shared API contract](https://github.com/protogulix/pantin/blob/master/packages/protocol/src/api.ts): `packages/protocol/src/api.ts`
- [HTTP server](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/server.ts): `packages/core/src/http/server.ts`
- [HTTP route dispatch](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/routes.ts): `packages/core/src/http/routes.ts`
- [Assembly routes](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/assembly-routes.ts): `packages/core/src/http/assembly-routes.ts`
- [Joint and pose routes](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/joint-routes.ts): `packages/core/src/http/joint-routes.ts`
- [Request decoding](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/request-reading.ts): `packages/core/src/http/request-reading.ts`
- [API responses](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/responses.ts): `packages/core/src/http/responses.ts`
- [Route context](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/route-context.ts): `packages/core/src/http/route-context.ts`

### Core domain

- [Input validation](https://github.com/protogulix/pantin/blob/master/packages/core/src/domain/validation.ts): `packages/core/src/domain/validation.ts`
- [Pantin service](https://github.com/protogulix/pantin/blob/master/packages/core/src/service/pantin-service.ts): `packages/core/src/service/pantin-service.ts`
- [Assembly and joint model](https://github.com/protogulix/pantin/tree/master/packages/core/src/domain): `packages/core/src/domain`
- [Pose simulation](https://github.com/protogulix/pantin/blob/master/packages/core/src/service/simulation.ts): `packages/core/src/service/simulation.ts`
- [Pose stream](https://github.com/protogulix/pantin/blob/master/packages/core/src/http/pose-stream-routes.ts): `packages/core/src/http/pose-stream-routes.ts`

### Import conversion

- [STEP converter](https://github.com/protogulix/pantin/blob/master/packages/core/src/converter/step-converter.ts): `packages/core/src/converter/step-converter.ts`
- [STEP conversion engine](https://github.com/protogulix/pantin/blob/master/packages/step-converter/src/pantin_step_converter/conversion.py): `packages/step-converter/src/pantin_step_converter/conversion.py`

### Persistence and runtime

- [Folder validation CLI](https://github.com/protogulix/pantin/blob/master/packages/cli/src/validate-folder.ts): `packages/cli/src/validate-folder.ts`
- [Pantin file store](https://github.com/protogulix/pantin/blob/master/packages/core/src/store/pantin-store.ts): `packages/core/src/store/pantin-store.ts`

### Other components

- **Editor user**
- **CLI user**

## Connections

- Editor user → Viewer application: uses (evidence: `packages/viewer/src/main.ts`)
- Viewer application → Editor controller: wires intents (evidence: `packages/viewer/src/main.ts`)
- Editor controller → Editor state: updates (evidence: `packages/viewer/src/controller/controller.ts`)
- Editor controller → Tree state and IDs: selects nodes (evidence: `packages/viewer/src/controller/controller.ts`)
- Editor controller → API client: requests actions
- Viewer application → 3D viewport: creates view (evidence: `packages/viewer/src/main.ts`)
- Viewer application → View model: renders model (evidence: `packages/viewer/src/main.ts`)
- Editor state → Tree state and IDs: checks nodes (evidence: `packages/viewer/src/viewer-state.ts`)
- Editor state → Assembly display: tracks display (evidence: `packages/viewer/src/viewer-state.ts`)
- Editor state → Joint editor: stores form (evidence: `packages/viewer/src/viewer-state.ts`)
- Viewer application → Translations: loads language (evidence: `packages/viewer/src/main.ts`)
- Viewer application → Editor messages: shows messages (evidence: `packages/viewer/src/main.ts`)
- API client → API transport: sends requests (evidence: `packages/viewer/src/api-client.ts`)
- API transport → Shared API contract: validates payloads (evidence: `packages/viewer/src/api-transport.ts`)
- HTTP server → HTTP route dispatch: dispatches requests
- HTTP route dispatch → Assembly routes: registers routes (evidence: `packages/core/src/http/routes.ts`)
- HTTP route dispatch → Joint and pose routes: registers routes (evidence: `packages/core/src/http/routes.ts`)
- HTTP route dispatch → Request decoding: decodes requests (evidence: `packages/core/src/http/routes.ts`)
- HTTP route dispatch → API responses: sends responses (evidence: `packages/core/src/http/routes.ts`)
- HTTP route dispatch → Route context: builds context (evidence: `packages/core/src/http/routes.ts`)
- Assembly routes → Pantin service: calls operations (evidence: `packages/core/src/http/assembly-routes.ts`)
- Joint and pose routes → Pantin service: calls operations (evidence: `packages/core/src/http/joint-routes.ts`)
- Assembly routes → Input validation: validates input (evidence: `packages/core/src/http/assembly-routes.ts`)
- Joint and pose routes → Input validation: validates input (evidence: `packages/core/src/http/joint-routes.ts`)
- Route context → Pantin service: types service (evidence: `packages/core/src/http/route-context.ts`)
- Pantin service → Pantin file store: reads and writes (evidence: `packages/core/src/service/pantin-service.ts`)
- Pantin service → Assembly and joint model: delegates operations (evidence: `packages/core/src/service/pantin-service.ts`)
- Pantin service → STEP converter: imports bodies (evidence: `packages/core/src/service/pantin-service.ts`)
- Pantin service → Pose simulation: runs steps (evidence: `packages/core/src/service/pantin-service.ts`)
- HTTP route dispatch → Pose stream: registers stream (evidence: `packages/core/src/http/routes.ts`)
- Pose stream → Route context: uses context (evidence: `packages/core/src/http/pose-stream-routes.ts`)
- STEP converter → STEP conversion engine: invokes converter
- CLI user → Folder validation CLI: runs validation
- Folder validation CLI → Pantin service: checks projects (evidence: `packages/cli/src/validate-folder.ts`)