# mridulsrivastavaaa/fsoc_tracker architecture

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

- Interactive diagram: https://gitdiagram.com/mridulsrivastavaaa/fsoc_tracker
- Repository: https://github.com/mridulsrivastavaaa/fsoc_tracker

## Overview

NETRA is an FSOC virtual-camera tracking and coarse-alignment system, with a Python tracking engine and a React/Three.js mission-control application. The operator workflow configures a scenario, runs a closed-loop simulation or video analysis, and inspects tracking telemetry and results. The Python engine coordinates scene input, disturbances, perception, tracking, and camera control; the web engine provides a parallel local simulation and the HUD presents its state. The README documents desktop and server operation as well. Some subsystem connections are documented rather than verified in sampled implementation excerpts.

Main entry points: [`fsoc_engine/src/fsoc/core/engine.py`](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/core/engine.py) (Closed-loop engine), [`web/src/core/engine.ts`](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/engine.ts) (Web simulation), [`fsoc_engine/src/fsoc/cli/main.py`](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/cli/main.py) (CLI), [`web/src/app/App.tsx`](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/app/App.tsx) (Mission-control UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_py_entry["Python entry points"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_py_runtime["Python tracking runtime"]
  node_config["Python config<br/>[config.py]"]
  node_sim_source["Scene source<br/>[sim_source.py]"]
  node_disturbance["Disturbances<br/>[engine.py]"]
  node_preprocess["Image preprocessing<br/>[preprocess.py]"]
  node_detector["Beacon detector<br/>[detector.py]"]
  node_cnn["CNN verifier<br/>[cnn_verifier.py]"]
  node_optical_flow["Optical flow<br/>[optical_flow.py]"]
  node_wide_search["Wide search<br/>[wide_search.py]"]
  node_kalman["Kalman tracker<br/>[kalman.py]"]
  node_imm["IMM tracker<br/>[imm.py]"]
  node_particle["Particle recovery<br/>[particle_filter.py]"]
  node_state_machine["Track state<br/>[state_machine.py]"]
  node_pid["PID control<br/>[pid_controller.py]"]
  node_adaptive["Adaptive control"]
  node_py_engine["Closed-loop engine<br/>[engine.py]"]
  node_video_source["Video input<br/>[video_source.py]"]
end

subgraph group_web_runtime["Web simulation"]
  node_web_config["Web config<br/>[config.ts]"]
  node_web_engine["Web simulation<br/>[engine.ts]"]
  node_web_detection["Web detection<br/>[registry.ts]"]
  node_web_control["Web gimbal control<br/>[gimbal.ts]"]
  node_worker["Simulation worker<br/>[worker.ts]"]
  node_batch_worker["Batch worker<br/>[batch.worker.ts]"]
end

subgraph group_web_ui["Web mission control"]
  node_web_store[("Application state<br/>[store.ts]")]
  node_web_app["Mission-control UI<br/>[App.tsx]"]
  node_web_report["Analysis report<br/>[report.ts]"]
  node_scene["3D scene<br/>[Stage.tsx]"]
  node_video_analysis["Video analysis<br/>[analyzer.ts]"]
end

subgraph group_interfaces["Operator interfaces"]
  node_server["Telemetry server<br/>[app.py]"]
  node_desktop["Desktop GUI<br/>[app.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"runs simulation"| node_py_engine
node_cli -.->|"launches service"| node_server
node_cli -->|"launches GUI"| node_desktop
node_py_engine -->|"uses settings"| node_config
node_py_engine -->|"gets frames"| node_sim_source
node_py_engine -->|"applies effects"| node_disturbance
node_py_engine -->|"processes frames"| node_preprocess
node_py_engine -->|"finds candidates"| node_detector
node_py_engine -->|"verifies candidates"| node_cnn
node_py_engine -->|"estimates flow"| node_optical_flow
node_py_engine -->|"searches field"| node_wide_search
node_py_engine -->|"tracks target"| node_imm
node_py_engine -->|"tracks target"| node_kalman
node_py_engine -->|"recovers lock"| node_particle
node_py_engine -->|"updates state"| node_state_machine
node_py_engine -->|"commands camera"| node_pid
node_py_engine -->|"adapts control"| node_adaptive
node_py_engine -.->|"accepts video"| node_video_source
node_server -->|"runs tracking"| node_py_engine
node_server -->|"analyzes video"| node_video_source
node_operator -->|"uses mission control"| node_web_app
node_web_app -->|"reads state"| node_web_store
node_web_app -->|"renders scene"| node_scene
node_web_store -->|"dispatches commands"| node_worker
node_web_store -->|"builds analysis"| node_web_report
node_worker -->|"runs simulation"| node_web_engine
node_batch_worker -->|"runs batches"| node_web_engine
node_web_engine -->|"uses settings"| node_web_config
node_web_engine -->|"creates detector"| node_web_detection
node_web_engine -->|"controls gimbal"| node_web_control
node_web_app -.->|"offers video bench"| node_video_analysis

click node_cli "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/cli/main.py"
click node_config "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/core/config.py"
click node_sim_source "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/simulation/sim_source.py"
click node_disturbance "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/disturbances/engine.py"
click node_preprocess "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/preprocess.py"
click node_detector "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/detector.py"
click node_cnn "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/cnn_verifier.py"
click node_optical_flow "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/optical_flow.py"
click node_wide_search "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/wide_search.py"
click node_kalman "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/kalman.py"
click node_imm "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/imm.py"
click node_particle "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/particle_filter.py"
click node_state_machine "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/state_machine.py"
click node_pid "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/control/pid_controller.py"
click node_adaptive "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/advanced/adaptive_controller.py"
click node_py_engine "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/core/engine.py"
click node_video_source "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/video/video_source.py"
click node_server "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/server/app.py"
click node_desktop "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/gui/app.py"
click node_web_config "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/config.ts"
click node_web_engine "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/engine.ts"
click node_web_detection "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/detection/registry.ts"
click node_web_control "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/control/gimbal.ts"
click node_worker "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/engine/worker.ts"
click node_batch_worker "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/engine/batch.worker.ts"
click node_web_store "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/state/store.ts"
click node_web_app "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/app/App.tsx"
click node_web_report "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/analysis/report.ts"
click node_scene "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/scene/Stage.tsx"
click node_video_analysis "https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/video/analyzer.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 toneBlue
class node_config,node_sim_source,node_disturbance,node_preprocess,node_detector,node_cnn,node_optical_flow,node_wide_search,node_kalman,node_imm,node_particle,node_state_machine,node_pid,node_adaptive,node_py_engine,node_video_source toneAmber
class node_web_config,node_web_engine,node_web_detection,node_web_control,node_worker,node_batch_worker toneMint
class node_web_store,node_web_app,node_web_report,node_scene,node_video_analysis toneRose
class node_server,node_desktop,node_operator toneIndigo
```

## Components

### Python entry points

- [CLI](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/cli/main.py): `fsoc_engine/src/fsoc/cli/main.py`

### Python tracking runtime

- [Python config](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/core/config.py): `fsoc_engine/src/fsoc/core/config.py`
- [Scene source](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/simulation/sim_source.py): `fsoc_engine/src/fsoc/simulation/sim_source.py`
- [Disturbances](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/disturbances/engine.py): `fsoc_engine/src/fsoc/disturbances/engine.py`
- [Image preprocessing](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/preprocess.py): `fsoc_engine/src/fsoc/vision/preprocess.py`
- [Beacon detector](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/detector.py): `fsoc_engine/src/fsoc/vision/detector.py`
- [CNN verifier](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/cnn_verifier.py): `fsoc_engine/src/fsoc/vision/cnn_verifier.py`
- [Optical flow](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/optical_flow.py): `fsoc_engine/src/fsoc/vision/optical_flow.py`
- [Wide search](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/vision/wide_search.py): `fsoc_engine/src/fsoc/vision/wide_search.py`
- [Kalman tracker](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/kalman.py): `fsoc_engine/src/fsoc/tracking/kalman.py`
- [IMM tracker](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/imm.py): `fsoc_engine/src/fsoc/tracking/imm.py`
- [Particle recovery](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/particle_filter.py): `fsoc_engine/src/fsoc/tracking/particle_filter.py`
- [Track state](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/tracking/state_machine.py): `fsoc_engine/src/fsoc/tracking/state_machine.py`
- [PID control](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/control/pid_controller.py): `fsoc_engine/src/fsoc/control/pid_controller.py`
- [Adaptive control](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/advanced/adaptive_controller.py): `fsoc_engine/src/fsoc/advanced/adaptive_controller.py`
- [Closed-loop engine](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/core/engine.py): `fsoc_engine/src/fsoc/core/engine.py`
- [Video input](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/video/video_source.py): `fsoc_engine/src/fsoc/video/video_source.py`

### Web simulation

- [Web config](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/config.ts): `web/src/core/config.ts`
- [Web simulation](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/engine.ts): `web/src/core/engine.ts`
- [Web detection](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/detection/registry.ts): `web/src/core/detection/registry.ts`
- [Web gimbal control](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/control/gimbal.ts): `web/src/core/control/gimbal.ts`
- [Simulation worker](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/engine/worker.ts): `web/src/engine/worker.ts`
- [Batch worker](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/engine/batch.worker.ts): `web/src/engine/batch.worker.ts`

### Web mission control

- [Application state](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/state/store.ts): `web/src/state/store.ts`
- [Mission-control UI](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/app/App.tsx): `web/src/app/App.tsx`
- [Analysis report](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/analysis/report.ts): `web/src/core/analysis/report.ts`
- [3D scene](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/scene/Stage.tsx): `web/src/scene/Stage.tsx`
- [Video analysis](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/web/src/core/video/analyzer.ts): `web/src/core/video/analyzer.ts`

### Operator interfaces

- [Telemetry server](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/server/app.py): `fsoc_engine/src/fsoc/server/app.py`
- [Desktop GUI](https://github.com/mridulsrivastavaaa/fsoc_tracker/blob/main/fsoc_engine/src/fsoc/gui/app.py): `fsoc_engine/src/fsoc/gui/app.py`

### Other components

- **Operator**

## Connections

- Operator → CLI: runs commands
- CLI → Closed-loop engine: runs simulation (evidence: `fsoc_engine/src/fsoc/cli/main.py`)
- CLI → Telemetry server: launches service
- CLI → Desktop GUI: launches GUI (evidence: `fsoc_engine/src/fsoc/cli/main.py`)
- Closed-loop engine → Python config: uses settings (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Scene source: gets frames (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Disturbances: applies effects (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Image preprocessing: processes frames (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Beacon detector: finds candidates (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → CNN verifier: verifies candidates (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Optical flow: estimates flow (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Wide search: searches field (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → IMM tracker: tracks target (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Kalman tracker: tracks target (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Particle recovery: recovers lock (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Track state: updates state (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → PID control: commands camera (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Adaptive control: adapts control (evidence: `fsoc_engine/src/fsoc/core/engine.py`)
- Closed-loop engine → Video input: accepts video
- Telemetry server → Closed-loop engine: runs tracking (evidence: `fsoc_engine/src/fsoc/server/app.py`)
- Telemetry server → Video input: analyzes video (evidence: `fsoc_engine/src/fsoc/server/app.py`)
- Operator → Mission-control UI: uses mission control
- Mission-control UI → Application state: reads state (evidence: `web/src/app/App.tsx`)
- Mission-control UI → 3D scene: renders scene (evidence: `web/src/app/App.tsx`)
- Application state → Simulation worker: dispatches commands (evidence: `web/src/state/store.ts`)
- Application state → Analysis report: builds analysis (evidence: `web/src/state/store.ts`)
- Simulation worker → Web simulation: runs simulation (evidence: `web/src/engine/worker.ts`)
- Batch worker → Web simulation: runs batches (evidence: `web/src/engine/batch.worker.ts`)
- Web simulation → Web config: uses settings (evidence: `web/src/core/engine.ts`)
- Web simulation → Web detection: creates detector (evidence: `web/src/core/engine.ts`)
- Web simulation → Web gimbal control: controls gimbal (evidence: `web/src/core/engine.ts`)
- Mission-control UI → Video analysis: offers video bench
