# senior-ict/senior architecture

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

- Interactive diagram: https://gitdiagram.com/senior-ict/senior
- Repository: https://github.com/senior-ict/senior

## Overview

Cubit's workflow takes phone photos of an object beside a known-size reference cube, checks framing, estimates geometry with VGGT, identifies marker bands and a proposed cut, then reconstructs and measures an approved watertight mesh. The browser front end supports framing review, cut placement and remeasurement; the compute service submits and serves pipeline jobs. The graph includes the sampled neural-network and geometry layers. Some service, stage and UI wiring is documented rather than visible in excerpts, so those links cite the README or are omitted where evidence is insufficient.

Main entry points: [`pipeline/orchestrator.py`](https://github.com/senior-ict/senior/blob/main/pipeline/orchestrator.py) (Stage runner), [`service/app.py`](https://github.com/senior-ict/senior/blob/main/service/app.py) (Job service), [`web/src/components/screens`](https://github.com/senior-ict/senior/tree/main/web/src/components/screens) (Review screens), [`web/src/components/three/CutReview.tsx`](https://github.com/senior-ict/senior/blob/main/web/src/components/three/CutReview.tsx) (Cut review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and review"]
  node_service["Job service<br/>[app.py]"]
  node_jobs["Job registry<br/>[jobs.py]"]
end

subgraph group_compute["Measurement pipeline"]
  node_orchestrator["Stage runner<br/>[orchestrator.py]"]
  node_prep["Framing gate<br/>[prep.py]"]
  node_config["Pipeline config<br/>[config.py]"]
  node_inference["VGGT inference<br/>[inference.py]"]
  node_vlm["Visual detector<br/>[vlm_detect.py]"]
end

subgraph group_geometry["Geometry processing"]
  node_pointcloud["Point cloud<br/>[pointcloud.py]"]
  node_clean["Clean and segment<br/>[clean.py]"]
  node_segmentation["Marker segmentation<br/>[segmentation.py]"]
  node_bands["3D band detection<br/>[bands3d.py]"]
  node_reconstruct["Surface reconstruction<br/>[reconstruct.py]"]
  node_watertight["Watertight cut<br/>[watertight.py]"]
  node_volume["Volume measurement<br/>[volume.py]"]
  node_mesh["Mesh operations<br/>[mesh.py]"]
end

subgraph group_model["VGGT inference"]
  node_vggt["VGGT model<br/>[vggt.py]"]
  node_aggregator["Feature aggregator<br/>[aggregator.py]"]
  node_block["Transformer block<br/>[block.py]"]
  node_dpt["Point-map head<br/>[dpt_head.py]"]
end

subgraph group_frontend["Browser application"]
  node_webui["Review screens"]
  node_cutui["Cut review<br/>[CutReview.tsx]"]
  node_ply["PLY loader<br/>[usePly.ts]"]
  node_api["Web API<br/>[api.ts]"]
end

node_user(("Operator"))

node_user -->|"submits photos"| node_webui
node_webui -->|"requests jobs"| node_api
node_api -.->|"calls service"| node_service
node_service -->|"queues work"| node_jobs
node_service -->|"runs stages"| node_orchestrator
node_service -->|"serves artifacts"| node_webui
node_webui -.->|"opens cut review"| node_cutui
node_cutui -->|"loads meshes"| node_ply
node_user -->|"approves cut"| node_cutui
node_cutui -->|"submits recut"| node_service
node_orchestrator -->|"runs framing"| node_prep
node_orchestrator -->|"runs inference"| node_inference
node_orchestrator -->|"builds points"| node_pointcloud
node_orchestrator -->|"cleans points"| node_clean
node_orchestrator -->|"detects bands"| node_bands
node_orchestrator -->|"reconstructs surface"| node_reconstruct
node_orchestrator -->|"cuts solid"| node_watertight
node_orchestrator -->|"measures volume"| node_volume
node_prep -->|"detects objects"| node_vlm
node_inference -->|"runs model"| node_vggt
node_vggt -->|"aggregates features"| node_aggregator
node_vggt -->|"predicts maps"| node_dpt
node_aggregator -->|"uses blocks"| node_block
node_clean -->|"segments markers"| node_segmentation
node_reconstruct -->|"builds meshes"| node_mesh
node_watertight -->|"repairs and cuts"| node_mesh
node_volume -->|"reads calibration"| node_config
node_prep -->|"reads settings"| node_config
node_segmentation -->|"reads thresholds"| node_config

click node_webui "https://github.com/senior-ict/senior/tree/main/web/src/components/screens"
click node_cutui "https://github.com/senior-ict/senior/blob/main/web/src/components/three/CutReview.tsx"
click node_ply "https://github.com/senior-ict/senior/blob/main/web/src/components/three/usePly.ts"
click node_api "https://github.com/senior-ict/senior/blob/main/web/src/lib/api.ts"
click node_service "https://github.com/senior-ict/senior/blob/main/service/app.py"
click node_jobs "https://github.com/senior-ict/senior/blob/main/service/jobs.py"
click node_orchestrator "https://github.com/senior-ict/senior/blob/main/pipeline/orchestrator.py"
click node_prep "https://github.com/senior-ict/senior/blob/main/pipeline/stages/prep.py"
click node_config "https://github.com/senior-ict/senior/blob/main/pipeline/config.py"
click node_inference "https://github.com/senior-ict/senior/blob/main/pipeline/stages/inference.py"
click node_vggt "https://github.com/senior-ict/senior/blob/main/vggt/models/vggt.py"
click node_aggregator "https://github.com/senior-ict/senior/blob/main/vggt/models/aggregator.py"
click node_block "https://github.com/senior-ict/senior/blob/main/vggt/layers/block.py"
click node_dpt "https://github.com/senior-ict/senior/blob/main/vggt/heads/dpt_head.py"
click node_pointcloud "https://github.com/senior-ict/senior/blob/main/pipeline/stages/pointcloud.py"
click node_clean "https://github.com/senior-ict/senior/blob/main/pipeline/stages/clean.py"
click node_segmentation "https://github.com/senior-ict/senior/blob/main/pipeline/core/segmentation.py"
click node_bands "https://github.com/senior-ict/senior/blob/main/pipeline/core/bands3d.py"
click node_reconstruct "https://github.com/senior-ict/senior/blob/main/pipeline/stages/reconstruct.py"
click node_watertight "https://github.com/senior-ict/senior/blob/main/pipeline/stages/watertight.py"
click node_volume "https://github.com/senior-ict/senior/blob/main/pipeline/stages/volume.py"
click node_vlm "https://github.com/senior-ict/senior/blob/main/pipeline/core/vlm_detect.py"
click node_mesh "https://github.com/senior-ict/senior/blob/main/pipeline/core/mesh.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_service,node_jobs toneBlue
class node_orchestrator,node_prep,node_config,node_inference,node_vlm toneAmber
class node_pointcloud,node_clean,node_segmentation,node_bands,node_reconstruct,node_watertight,node_volume,node_mesh toneMint
class node_vggt,node_aggregator,node_block,node_dpt toneRose
class node_webui,node_cutui,node_ply,node_api,node_user toneIndigo
```

## Components

### Capture and review

- [Job service](https://github.com/senior-ict/senior/blob/main/service/app.py): `service/app.py`
- [Job registry](https://github.com/senior-ict/senior/blob/main/service/jobs.py): `service/jobs.py`

### Measurement pipeline

- [Stage runner](https://github.com/senior-ict/senior/blob/main/pipeline/orchestrator.py): `pipeline/orchestrator.py`
- [Framing gate](https://github.com/senior-ict/senior/blob/main/pipeline/stages/prep.py): `pipeline/stages/prep.py`
- [Pipeline config](https://github.com/senior-ict/senior/blob/main/pipeline/config.py): `pipeline/config.py`
- [VGGT inference](https://github.com/senior-ict/senior/blob/main/pipeline/stages/inference.py): `pipeline/stages/inference.py`
- [Visual detector](https://github.com/senior-ict/senior/blob/main/pipeline/core/vlm_detect.py): `pipeline/core/vlm_detect.py`

### Geometry processing

- [Point cloud](https://github.com/senior-ict/senior/blob/main/pipeline/stages/pointcloud.py): `pipeline/stages/pointcloud.py`
- [Clean and segment](https://github.com/senior-ict/senior/blob/main/pipeline/stages/clean.py): `pipeline/stages/clean.py`
- [Marker segmentation](https://github.com/senior-ict/senior/blob/main/pipeline/core/segmentation.py): `pipeline/core/segmentation.py`
- [3D band detection](https://github.com/senior-ict/senior/blob/main/pipeline/core/bands3d.py): `pipeline/core/bands3d.py`
- [Surface reconstruction](https://github.com/senior-ict/senior/blob/main/pipeline/stages/reconstruct.py): `pipeline/stages/reconstruct.py`
- [Watertight cut](https://github.com/senior-ict/senior/blob/main/pipeline/stages/watertight.py): `pipeline/stages/watertight.py`
- [Volume measurement](https://github.com/senior-ict/senior/blob/main/pipeline/stages/volume.py): `pipeline/stages/volume.py`
- [Mesh operations](https://github.com/senior-ict/senior/blob/main/pipeline/core/mesh.py): `pipeline/core/mesh.py`

### VGGT inference

- [VGGT model](https://github.com/senior-ict/senior/blob/main/vggt/models/vggt.py): `vggt/models/vggt.py`
- [Feature aggregator](https://github.com/senior-ict/senior/blob/main/vggt/models/aggregator.py): `vggt/models/aggregator.py`
- [Transformer block](https://github.com/senior-ict/senior/blob/main/vggt/layers/block.py): `vggt/layers/block.py`
- [Point-map head](https://github.com/senior-ict/senior/blob/main/vggt/heads/dpt_head.py): `vggt/heads/dpt_head.py`

### Browser application

- [Review screens](https://github.com/senior-ict/senior/tree/main/web/src/components/screens): `web/src/components/screens`
- [Cut review](https://github.com/senior-ict/senior/blob/main/web/src/components/three/CutReview.tsx): `web/src/components/three/CutReview.tsx`
- [PLY loader](https://github.com/senior-ict/senior/blob/main/web/src/components/three/usePly.ts): `web/src/components/three/usePly.ts`
- [Web API](https://github.com/senior-ict/senior/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`

### Other components

- **Operator**

## Connections

- Operator → Review screens: submits photos (evidence: `README.md`)
- Review screens → Web API: requests jobs (evidence: `README.md`)
- Web API → Job service: calls service
- Job service → Job registry: queues work (evidence: `service/app.py`)
- Job service → Stage runner: runs stages (evidence: `service/app.py`)
- Job service → Review screens: serves artifacts (evidence: `service/app.py`)
- Review screens → Cut review: opens cut review
- Cut review → PLY loader: loads meshes (evidence: `web/src/components/three/CutReview.tsx`)
- Operator → Cut review: approves cut (evidence: `README.md`)
- Cut review → Job service: submits recut (evidence: `README.md`)
- Stage runner → Framing gate: runs framing (evidence: `pipeline/orchestrator.py`)
- Stage runner → VGGT inference: runs inference (evidence: `pipeline/orchestrator.py`)
- Stage runner → Point cloud: builds points (evidence: `pipeline/orchestrator.py`)
- Stage runner → Clean and segment: cleans points (evidence: `pipeline/orchestrator.py`)
- Stage runner → 3D band detection: detects bands (evidence: `pipeline/orchestrator.py`)
- Stage runner → Surface reconstruction: reconstructs surface (evidence: `pipeline/orchestrator.py`)
- Stage runner → Watertight cut: cuts solid (evidence: `pipeline/orchestrator.py`)
- Stage runner → Volume measurement: measures volume (evidence: `pipeline/orchestrator.py`)
- Framing gate → Visual detector: detects objects (evidence: `pipeline/stages/prep.py`)
- VGGT inference → VGGT model: runs model (evidence: `pipeline/stages/inference.py`)
- VGGT model → Feature aggregator: aggregates features (evidence: `vggt/models/vggt.py`)
- VGGT model → Point-map head: predicts maps (evidence: `vggt/models/vggt.py`)
- Feature aggregator → Transformer block: uses blocks (evidence: `vggt/models/aggregator.py`)
- Clean and segment → Marker segmentation: segments markers (evidence: `pipeline/stages/clean.py`)
- Surface reconstruction → Mesh operations: builds meshes (evidence: `pipeline/stages/reconstruct.py`)
- Watertight cut → Mesh operations: repairs and cuts (evidence: `pipeline/stages/watertight.py`)
- Volume measurement → Pipeline config: reads calibration (evidence: `pipeline/stages/volume.py`)
- Framing gate → Pipeline config: reads settings (evidence: `pipeline/stages/prep.py`)
- Marker segmentation → Pipeline config: reads thresholds (evidence: `pipeline/core/segmentation.py`)
