# foxlendor/twinthink architecture

> Architecture diagram of the GitHub repository foxlendor/twinthink, 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/foxlendor/twinthink
- Repository: https://github.com/foxlendor/twinthink

## Overview

TwinThink is a platform for compiling, validating, and sharing digital twins of physical inventions. Its main workflow runs from creator input and twin ingestion through canonical twin/BOM modeling, validation and simulation, then persistence and inspection or export. The repository also documents a browser UI, cryptographic identity and portable bundles, and an MCP interface. Edges are limited to relationships shown in the excerpts, SOURCE INDEX references, or README; some UI/API wiring and unsampled capabilities are therefore shown without speculative call paths.

Main entry points: [`packages/twinthink/service.py`](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/service.py) (Twin service), [`apps/api/main.py`](https://github.com/foxlendor/twinthink/blob/master/apps/api/main.py) (HTTP API), [`packages/twinthink/factory/engine.py`](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/factory/engine.py) (Twin ingestion), [`apps/web/src/app/page.tsx`](https://github.com/foxlendor/twinthink/blob/master/apps/web/src/app/page.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web_app["Web application<br/>[page.tsx]"]
  node_twin_viewer["Twin viewer<br/>[TwinViewer.tsx]"]
  node_shadowfield["ShadowField<br/>[ShadowField.tsx]"]
  node_api["HTTP API<br/>[main.py]"]
  node_cli["CLI<br/>[tt.py]"]
  node_mcp["MCP server<br/>[server.py]"]
end

subgraph group_twin_core["Twin lifecycle"]
  node_factory["Twin ingestion<br/>[engine.py]"]
  node_schema["Twin schema<br/>[schema.py]"]
  node_service["Twin service<br/>[service.py]"]
  node_validator["Twin validator<br/>[validator.py]"]
end

subgraph group_engineering["Engineering analysis"]
  node_bom["BOM engine<br/>[engine.py]"]
  node_reality["Reality scoring<br/>[calculator.py]"]
  node_calibration["Calibration<br/>[calibration.py]"]
  node_thermal["Thermal simulation<br/>[thermal.py]"]
  node_flow["Flow model<br/>[flow.py]"]
end

subgraph group_trust["Trust and exchange"]
  node_identity["Creator identity<br/>[identity.py]"]
  node_revision["Signed revisions<br/>[revision.py]"]
  node_envelope["Encrypted segments<br/>[envelope.py]"]
  node_bundle["Portable bundles<br/>[bundle.py]"]
end

subgraph group_persistence["Persistence"]
  node_sqlite[("Local SQLite")]
end

node_creator(("Creator"))

node_creator -->|"uses"| node_web_app
node_creator -->|"submits twins"| node_api
node_web_app -.->|"previews"| node_twin_viewer
node_web_app -.->|"explores"| node_shadowfield
node_web_app -.->|"requests data"| node_api
node_api -.->|"ingests"| node_factory
node_api -->|"validates"| node_validator
node_api -->|"simulates"| node_thermal
node_api -->|"uses"| node_flow
node_api -->|"calibrates"| node_calibration
node_api -->|"persists"| node_sqlite
node_cli -->|"delegates"| node_service
node_mcp -->|"delegates"| node_service
node_service -->|"uses"| node_schema
node_service -->|"parses BOM"| node_bom
node_service -->|"simulates"| node_thermal
node_service -->|"uses"| node_flow
node_service -->|"calibrates"| node_calibration
node_factory -->|"builds"| node_schema
node_factory -->|"scores"| node_reality
node_factory -->|"compares"| node_calibration
node_factory -->|"constructs"| node_bom
node_thermal -->|"reads timeline"| node_flow
node_thermal -.->|"uses PCM"| node_identity
node_service -->|"signs identity"| node_identity
node_service -->|"records revisions"| node_revision
node_service -->|"exports bundles"| node_bundle
node_bundle -->|"verifies identity"| node_identity
node_bundle -->|"verifies revisions"| node_revision
node_bundle -->|"uses encryption"| node_envelope

click node_web_app "https://github.com/foxlendor/twinthink/blob/master/apps/web/src/app/page.tsx"
click node_twin_viewer "https://github.com/foxlendor/twinthink/blob/master/apps/web/src/components/TwinViewer.tsx"
click node_shadowfield "https://github.com/foxlendor/twinthink/blob/master/apps/web/src/components/shadowfield/ShadowField.tsx"
click node_api "https://github.com/foxlendor/twinthink/blob/master/apps/api/main.py"
click node_cli "https://github.com/foxlendor/twinthink/blob/master/apps/api/tt.py"
click node_mcp "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/mcp/server.py"
click node_factory "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/factory/engine.py"
click node_schema "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/schema.py"
click node_service "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/service.py"
click node_validator "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/validator.py"
click node_bom "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/bom/engine.py"
click node_reality "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/reality/calculator.py"
click node_calibration "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/simulation/calibration.py"
click node_thermal "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/simulation/thermal.py"
click node_flow "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/simulation/flow.py"
click node_identity "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/identity.py"
click node_revision "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/revision.py"
click node_envelope "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/envelope.py"
click node_bundle "https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/bundle.py"

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_web_app,node_twin_viewer,node_shadowfield,node_api,node_cli,node_mcp toneBlue
class node_factory,node_schema,node_service,node_validator toneAmber
class node_bom,node_reality,node_calibration,node_thermal,node_flow toneMint
class node_identity,node_revision,node_envelope,node_bundle toneRose
class node_sqlite,node_creator toneIndigo
```

## Components

### User interfaces

- [Web application](https://github.com/foxlendor/twinthink/blob/master/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Twin viewer](https://github.com/foxlendor/twinthink/blob/master/apps/web/src/components/TwinViewer.tsx): `apps/web/src/components/TwinViewer.tsx`
- [ShadowField](https://github.com/foxlendor/twinthink/blob/master/apps/web/src/components/shadowfield/ShadowField.tsx): `apps/web/src/components/shadowfield/ShadowField.tsx`
- [HTTP API](https://github.com/foxlendor/twinthink/blob/master/apps/api/main.py): `apps/api/main.py`
- [CLI](https://github.com/foxlendor/twinthink/blob/master/apps/api/tt.py): `apps/api/tt.py`
- [MCP server](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/mcp/server.py): `packages/twinthink/mcp/server.py`

### Twin lifecycle

- [Twin ingestion](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/factory/engine.py): `packages/twinthink/factory/engine.py`
- [Twin schema](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/schema.py): `packages/twinthink/schema.py`
- [Twin service](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/service.py): `packages/twinthink/service.py`
- [Twin validator](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/validator.py): `packages/twinthink/validator.py`

### Engineering analysis

- [BOM engine](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/bom/engine.py): `packages/twinthink/bom/engine.py`
- [Reality scoring](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/reality/calculator.py): `packages/twinthink/reality/calculator.py`
- [Calibration](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/simulation/calibration.py): `packages/twinthink/simulation/calibration.py`
- [Thermal simulation](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/simulation/thermal.py): `packages/twinthink/simulation/thermal.py`
- [Flow model](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/simulation/flow.py): `packages/twinthink/simulation/flow.py`

### Trust and exchange

- [Creator identity](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/identity.py): `packages/twinthink/crypto/identity.py`
- [Signed revisions](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/revision.py): `packages/twinthink/crypto/revision.py`
- [Encrypted segments](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/envelope.py): `packages/twinthink/crypto/envelope.py`
- [Portable bundles](https://github.com/foxlendor/twinthink/blob/master/packages/twinthink/crypto/bundle.py): `packages/twinthink/crypto/bundle.py`

### Persistence

- **Local SQLite**

### Other components

- **Creator**

## Connections

- Creator → Web application: uses (evidence: `README.md`)
- Creator → HTTP API: submits twins (evidence: `README.md`)
- Web application → Twin viewer: previews
- Web application → ShadowField: explores
- Web application → HTTP API: requests data
- HTTP API → Twin ingestion: ingests
- HTTP API → Twin validator: validates (evidence: `apps/api/main.py`)
- HTTP API → Thermal simulation: simulates (evidence: `apps/api/main.py`)
- HTTP API → Flow model: uses (evidence: `apps/api/main.py`)
- HTTP API → Calibration: calibrates (evidence: `apps/api/main.py`)
- HTTP API → Local SQLite: persists (evidence: `README.md`)
- CLI → Twin service: delegates (evidence: `apps/api/tt.py`)
- MCP server → Twin service: delegates (evidence: `packages/twinthink/mcp/server.py`)
- Twin service → Twin schema: uses (evidence: `packages/twinthink/service.py`)
- Twin service → BOM engine: parses BOM (evidence: `packages/twinthink/service.py`)
- Twin service → Thermal simulation: simulates (evidence: `packages/twinthink/service.py`)
- Twin service → Flow model: uses (evidence: `packages/twinthink/service.py`)
- Twin service → Calibration: calibrates (evidence: `packages/twinthink/service.py`)
- Twin ingestion → Twin schema: builds (evidence: `packages/twinthink/factory/engine.py`)
- Twin ingestion → Reality scoring: scores (evidence: `packages/twinthink/factory/engine.py`)
- Twin ingestion → Calibration: compares (evidence: `packages/twinthink/factory/engine.py`)
- Twin ingestion → BOM engine: constructs (evidence: `packages/twinthink/factory/engine.py`)
- Thermal simulation → Flow model: reads timeline (evidence: `packages/twinthink/simulation/thermal.py`)
- Thermal simulation → Creator identity: uses PCM
- Twin service → Creator identity: signs identity (evidence: `packages/twinthink/service.py`)
- Twin service → Signed revisions: records revisions (evidence: `packages/twinthink/service.py`)
- Twin service → Portable bundles: exports bundles (evidence: `packages/twinthink/service.py`)
- Portable bundles → Creator identity: verifies identity (evidence: `packages/twinthink/crypto/bundle.py`)
- Portable bundles → Signed revisions: verifies revisions (evidence: `packages/twinthink/crypto/bundle.py`)
- Portable bundles → Encrypted segments: uses encryption (evidence: `packages/twinthink/crypto/bundle.py`)
