# isathinsitha/stackopt architecture

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

- Interactive diagram: https://gitdiagram.com/isathinsitha/stackopt
- Repository: https://github.com/isathinsitha/stackopt

## Overview

StackOpt is a Python CLI for worst-case dimensional tolerance analysis. The main workflow accepts a manual case or CAD-bound case, resolves and validates dimensions, optionally captures CAD provenance in a replayable snapshot, evaluates the clearance envelope, optionally searches tolerance assignments, and emits a terminal or JSON report. Separate from the runtime CLI, the repository includes an interactive architecture editor. The map preserves its central modules, but its detailed interactions are only partly visible in the sampled excerpts and source index.

Main entry points: [`src/stackopt/cli.py`](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/cli.py) (Command router), [`src/stackopt/analysis.py`](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/analysis.py) (Envelope analysis), [`stackopt-workspace/src/App.tsx`](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/App.tsx) (Editor application), [`src/stackopt/case.py`](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/case.py) (Case resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["Command router<br/>[cli.py]"]
  node_case["Case resolver<br/>[case.py]"]
  node_snapshot["Snapshot replay<br/>[snapshot.py]"]
  node_report["Result reports<br/>[report.py]"]
end

subgraph group_engineering["Analysis engine"]
  node_contracts["Data contracts<br/>[contracts.py]"]
  node_validation["Contract validation"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_analysis["Envelope analysis<br/>[analysis.py]"]
  node_allocation["Tolerance allocation<br/>[allocation.py]"]
end

subgraph group_cad["CAD extraction"]
  node_freecad["FreeCAD adapter<br/>[freecad.py]"]
  node_solidworks["SOLIDWORKS adapter<br/>[solidworks.py]"]
end

subgraph group_workspace["Architecture editor"]
  node_editor["Editor application<br/>[App.tsx]"]
  node_schema["Document schema<br/>[schema.ts]"]
  node_initial["Initial architecture<br/>[initial.ts]"]
  node_document["Document handling<br/>[document.ts]"]
  node_inspector["Component inspector<br/>[Inspector.tsx]"]
  node_diagram["Diagram layout<br/>[diagram.ts]"]
  node_model_layout["Model layout<br/>[model-layout.ts]"]
  node_pipeline_layout["Pipeline layout<br/>[pipeline-layout.ts]"]
  node_canvas["Diagram canvas<br/>[Canvas.tsx]"]
  node_export["Diagram export<br/>[export.ts]"]
end

node_user(("CLI user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"resolves cases"| node_case
node_cli -->|"extracts from"| node_freecad
node_cli -->|"extracts from"| node_solidworks
node_freecad -->|"records provenance"| node_snapshot
node_cli -->|"replays snapshots"| node_snapshot
node_case -->|"supplies resolved input"| node_analysis
node_snapshot -->|"supplies replay input"| node_analysis
node_cli -->|"runs allocation"| node_allocation
node_cli -->|"runs analysis"| node_analysis
node_cli -->|"renders results"| node_report
node_analysis -->|"evaluates candidates"| node_allocation
node_analysis -->|"provides evaluation"| node_report
node_case -->|"uses validation"| node_validation
node_snapshot -->|"parses embedded case"| node_case
node_validation -->|"validates shapes"| node_contracts
node_case -->|"builds typed data"| node_contracts
node_analysis -->|"consumes resolved data"| node_contracts
node_allocation -->|"evaluates assignments"| node_analysis
node_editor -->|"loads document"| node_document
node_document -->|"validates against"| node_schema
node_document -->|"uses defaults"| node_initial
node_editor -->|"uses inspector"| node_inspector
node_editor -->|"renders architecture"| node_diagram
node_diagram -->|"uses model layout"| node_model_layout
node_diagram -->|"uses pipeline layout"| node_pipeline_layout
node_editor -.->|"displays diagram"| node_canvas
node_editor -->|"exports diagrams"| node_export
node_export -->|"serializes diagram"| node_diagram

click node_cli "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/cli.py"
click node_case "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/case.py"
click node_snapshot "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/snapshot.py"
click node_report "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/report.py"
click node_freecad "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/adapters/freecad.py"
click node_solidworks "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/adapters/solidworks.py"
click node_contracts "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/contracts.py"
click node_validation "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/contract_validation.py"
click node_diagnostics "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/diagnostics.py"
click node_analysis "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/analysis.py"
click node_allocation "https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/allocation.py"
click node_editor "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/App.tsx"
click node_schema "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/schema.ts"
click node_initial "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/initial.ts"
click node_document "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/document.ts"
click node_inspector "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/Inspector.tsx"
click node_diagram "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/diagram.ts"
click node_model_layout "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/model-layout.ts"
click node_pipeline_layout "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/pipeline-layout.ts"
click node_canvas "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/Canvas.tsx"
click node_export "https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/export.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_cli,node_case,node_snapshot,node_report,node_user toneBlue
class node_contracts,node_validation,node_diagnostics,node_analysis,node_allocation toneAmber
class node_freecad,node_solidworks toneMint
class node_editor,node_schema,node_initial,node_document,node_inspector,node_diagram,node_model_layout,node_pipeline_layout,node_canvas,node_export toneRose
```

## Components

### CLI workflow

- [Command router](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/cli.py): `src/stackopt/cli.py`
- [Case resolver](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/case.py): `src/stackopt/case.py`
- [Snapshot replay](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/snapshot.py): `src/stackopt/snapshot.py`
- [Result reports](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/report.py): `src/stackopt/report.py`

### Analysis engine

- [Data contracts](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/contracts.py): `src/stackopt/contracts.py`
- [Contract validation](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/contract_validation.py): `src/stackopt/contract_validation.py`
- [Diagnostics](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/diagnostics.py): `src/stackopt/diagnostics.py`
- [Envelope analysis](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/analysis.py): `src/stackopt/analysis.py`
- [Tolerance allocation](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/allocation.py): `src/stackopt/allocation.py`

### CAD extraction

- [FreeCAD adapter](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/adapters/freecad.py): `src/stackopt/adapters/freecad.py`
- [SOLIDWORKS adapter](https://github.com/isathinsitha/stackopt/blob/main/src/stackopt/adapters/solidworks.py): `src/stackopt/adapters/solidworks.py`

### Architecture editor

- [Editor application](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/App.tsx): `stackopt-workspace/src/App.tsx`
- [Document schema](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/schema.ts): `stackopt-workspace/src/schema.ts`
- [Initial architecture](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/initial.ts): `stackopt-workspace/src/initial.ts`
- [Document handling](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/document.ts): `stackopt-workspace/src/document.ts`
- [Component inspector](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/Inspector.tsx): `stackopt-workspace/src/Inspector.tsx`
- [Diagram layout](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/diagram.ts): `stackopt-workspace/src/diagram.ts`
- [Model layout](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/model-layout.ts): `stackopt-workspace/src/model-layout.ts`
- [Pipeline layout](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/pipeline-layout.ts): `stackopt-workspace/src/pipeline-layout.ts`
- [Diagram canvas](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/Canvas.tsx): `stackopt-workspace/src/Canvas.tsx`
- [Diagram export](https://github.com/isathinsitha/stackopt/blob/main/stackopt-workspace/src/export.ts): `stackopt-workspace/src/export.ts`

### Other components

- **CLI user**

## Connections

- CLI user → Command router: runs commands (evidence: `README.md`)
- Command router → Case resolver: resolves cases (evidence: `README.md`)
- Command router → FreeCAD adapter: extracts from (evidence: `README.md`)
- Command router → SOLIDWORKS adapter: extracts from (evidence: `README.md`)
- FreeCAD adapter → Snapshot replay: records provenance (evidence: `README.md`)
- Command router → Snapshot replay: replays snapshots (evidence: `README.md`)
- Case resolver → Envelope analysis: supplies resolved input (evidence: `README.md`)
- Snapshot replay → Envelope analysis: supplies replay input (evidence: `README.md`)
- Command router → Tolerance allocation: runs allocation (evidence: `src/stackopt/cli.py`)
- Command router → Envelope analysis: runs analysis (evidence: `src/stackopt/cli.py`)
- Command router → Result reports: renders results (evidence: `src/stackopt/cli.py`)
- Envelope analysis → Tolerance allocation: evaluates candidates (evidence: `src/stackopt/allocation.py`)
- Envelope analysis → Result reports: provides evaluation (evidence: `src/stackopt/report.py`)
- Case resolver → Contract validation: uses validation (evidence: `src/stackopt/case.py`)
- Snapshot replay → Case resolver: parses embedded case (evidence: `src/stackopt/snapshot.py`)
- Contract validation → Data contracts: validates shapes (evidence: `src/stackopt/contract_validation.py`)
- Case resolver → Data contracts: builds typed data (evidence: `src/stackopt/case.py`)
- Envelope analysis → Data contracts: consumes resolved data (evidence: `src/stackopt/analysis.py`)
- Tolerance allocation → Envelope analysis: evaluates assignments (evidence: `src/stackopt/allocation.py`)
- Editor application → Document handling: loads document (evidence: `stackopt-workspace/src/App.tsx`)
- Document handling → Document schema: validates against (evidence: `stackopt-workspace/src/document.ts`)
- Document handling → Initial architecture: uses defaults (evidence: `stackopt-workspace/src/document.ts`)
- Editor application → Component inspector: uses inspector (evidence: `stackopt-workspace/src/App.tsx`)
- Editor application → Diagram layout: renders architecture (evidence: `stackopt-workspace/src/App.tsx`)
- Diagram layout → Model layout: uses model layout (evidence: `stackopt-workspace/src/diagram.ts`)
- Diagram layout → Pipeline layout: uses pipeline layout (evidence: `stackopt-workspace/src/diagram.ts`)
- Editor application → Diagram canvas: displays diagram (evidence: `stackopt-workspace/src/App.tsx`)
- Editor application → Diagram export: exports diagrams (evidence: `stackopt-workspace/src/App.tsx`)
- Diagram export → Diagram layout: serializes diagram (evidence: `stackopt-workspace/src/export.ts`)
