# kirtom/nepalvideo architecture

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

- Interactive diagram: https://gitdiagram.com/kirtom/nepalvideo
- Repository: https://github.com/kirtom/nepalvideo

## Overview

Nepal is a local trek-media-to-documentary pipeline. Its principal workflow probes raw media, builds a chronological story spine, processes clips into analyzable shots, then applies semantic analysis and scoring before assembly and rendering. The README also documents GPS/place enrichment, Telegram and music mapping, approval gates, and a short cut. Later-stage capabilities are included from the README and tree; their detailed internal wiring is not shown in the sampled source, so links there are limited to the documented stage flow.

Main entry points: [`src/nepal/stages/s02_spine.py`](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s02_spine.py) (S02 Spine), [`src/nepal/stages/s03_process.py`](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s03_process.py) (S03 Process), [`src/nepal/stages/s01_probe.py`](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s01_probe.py) (S01 Probe), [`src/nepal/cli.py`](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline control"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_probe["Probe and story"]
  node_s01["S01 Probe<br/>[s01_probe.py]"]
  node_manifest["Asset manifest<br/>[manifest.py]"]
  node_chapters["Chapter grouping<br/>[chapters.py]"]
  node_fov["Lens FOV<br/>[fov.py]"]
  node_clock["Clock offsets<br/>[clock.py]"]
  node_s02["S02 Spine<br/>[s02_spine.py]"]
  node_gps["GPS track<br/>[gps.py]"]
  node_dem["Elevation<br/>[dem.py]"]
  node_geocode["Place names<br/>[geocode.py]"]
  node_acts["Act boundaries<br/>[acts.py]"]
  node_telegram["Telegram story<br/>[telegram.py]"]
  node_music["Music map<br/>[music.py]"]
end

subgraph group_processing["Clip processing"]
  node_s03["S03 Process<br/>[s03_process.py]"]
  node_reproject["Proxy and views<br/>[reproject.py]"]
  node_shots["Shot detection<br/>[shots.py]"]
  node_metrics["Clip metrics<br/>[metrics.py]"]
  node_audio["Audio analysis<br/>[audio.py]"]
  node_asr["Speech transcription<br/>[asr.py]"]
  node_gate["Quality gate<br/>[gate.py]"]
end

subgraph group_editorial["Semantic and edit"]
  node_s04["S04 Semantic<br/>[s04_semantic.py]"]
  node_s05["S05 Score and cut<br/>[s05_cut.py]"]
  node_select["Shortlist<br/>[select.py]"]
  node_assemble["Assembly<br/>[assemble.py]"]
  node_render["Draft render<br/>[render.py]"]
end

subgraph group_state["State and references"]
  node_db[("Pipeline database<br/>[db.py]")]
  node_reference["Reference data<br/>[reference.py]"]
end

node_operator(("Operator"))
node_raw_media["Raw media"]
node_external_data["SRTM and GeoNames"]
node_film["Documentary and short"]

node_operator -->|"runs stages"| node_cli
node_raw_media -->|"probes files"| node_s01
node_cli -->|"dispatches"| node_s01
node_s01 -->|"builds inventory"| node_manifest
node_s01 -->|"groups chapters"| node_chapters
node_s01 -->|"solves lens"| node_fov
node_s01 -->|"solves offsets"| node_clock
node_s01 -->|"records results"| node_db
node_cli -->|"dispatches"| node_s02
node_s02 -->|"builds track"| node_gps
node_s02 -->|"adds elevation"| node_dem
node_s02 -->|"resolves places"| node_geocode
node_s02 -->|"sets acts"| node_acts
node_s02 -->|"processes messages"| node_telegram
node_s02 -->|"maps music"| node_music
node_s02 -->|"reads datasets"| node_reference
node_reference -->|"fetches"| node_external_data
node_s02 -->|"records story"| node_db
node_cli -->|"dispatches"| node_s03
node_s03 -->|"creates proxies"| node_reproject
node_s03 -->|"detects shots"| node_shots
node_s03 -->|"measures shots"| node_metrics
node_s03 -->|"analyzes audio"| node_audio
node_s03 -->|"transcribes speech"| node_asr
node_s03 -->|"gates quality"| node_gate
node_s03 -->|"records processing"| node_db
node_cli -->|"dispatches"| node_s04
node_s04 -->|"semantic inputs"| node_s05
node_cli -->|"dispatches"| node_s05
node_s05 -->|"ranks candidates"| node_select
node_s05 -->|"selects edit"| node_assemble
node_assemble -->|"builds draft"| node_render
node_render -->|"produces"| node_film

click node_cli "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/cli.py"
click node_s01 "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s01_probe.py"
click node_manifest "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/manifest.py"
click node_chapters "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/chapters.py"
click node_fov "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/fov.py"
click node_clock "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/clock.py"
click node_s02 "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s02_spine.py"
click node_gps "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/gps.py"
click node_dem "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/dem.py"
click node_geocode "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/geocode.py"
click node_acts "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/acts.py"
click node_telegram "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/telegram.py"
click node_music "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/music.py"
click node_s03 "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s03_process.py"
click node_reproject "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/reproject.py"
click node_shots "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/shots.py"
click node_metrics "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/metrics.py"
click node_audio "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/audio.py"
click node_asr "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/asr.py"
click node_gate "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/gate.py"
click node_s04 "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s04_semantic.py"
click node_s05 "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s05_cut.py"
click node_select "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/select.py"
click node_assemble "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/assemble.py"
click node_render "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/render.py"
click node_db "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/db.py"
click node_reference "https://github.com/kirtom/nepalvideo/blob/main/src/nepal/reference.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_cli toneBlue
class node_s01,node_manifest,node_chapters,node_fov,node_clock,node_s02,node_gps,node_dem,node_geocode,node_acts,node_telegram,node_music toneAmber
class node_s03,node_reproject,node_shots,node_metrics,node_audio,node_asr,node_gate toneMint
class node_s04,node_s05,node_select,node_assemble,node_render toneRose
class node_db,node_reference,node_operator,node_raw_media,node_external_data,node_film toneIndigo
```

## Components

### Pipeline control

- [CLI](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/cli.py): `src/nepal/cli.py`

### Probe and story

- [S01 Probe](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s01_probe.py): `src/nepal/stages/s01_probe.py`
- [Asset manifest](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/manifest.py): `src/nepal/probe/manifest.py`
- [Chapter grouping](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/chapters.py): `src/nepal/probe/chapters.py`
- [Lens FOV](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/fov.py): `src/nepal/probe/fov.py`
- [Clock offsets](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/probe/clock.py): `src/nepal/probe/clock.py`
- [S02 Spine](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s02_spine.py): `src/nepal/stages/s02_spine.py`
- [GPS track](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/gps.py): `src/nepal/spine/gps.py`
- [Elevation](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/dem.py): `src/nepal/spine/dem.py`
- [Place names](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/geocode.py): `src/nepal/spine/geocode.py`
- [Act boundaries](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/acts.py): `src/nepal/spine/acts.py`
- [Telegram story](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/telegram.py): `src/nepal/spine/telegram.py`
- [Music map](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/spine/music.py): `src/nepal/spine/music.py`

### Clip processing

- [S03 Process](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s03_process.py): `src/nepal/stages/s03_process.py`
- [Proxy and views](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/reproject.py): `src/nepal/process/reproject.py`
- [Shot detection](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/shots.py): `src/nepal/process/shots.py`
- [Clip metrics](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/metrics.py): `src/nepal/process/metrics.py`
- [Audio analysis](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/audio.py): `src/nepal/process/audio.py`
- [Speech transcription](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/asr.py): `src/nepal/process/asr.py`
- [Quality gate](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/gate.py): `src/nepal/process/gate.py`

### Semantic and edit

- [S04 Semantic](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s04_semantic.py): `src/nepal/stages/s04_semantic.py`
- [S05 Score and cut](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/stages/s05_cut.py): `src/nepal/stages/s05_cut.py`
- [Shortlist](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/select.py): `src/nepal/select.py`
- [Assembly](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/assemble.py): `src/nepal/process/assemble.py`
- [Draft render](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/process/render.py): `src/nepal/process/render.py`

### State and references

- [Pipeline database](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/db.py): `src/nepal/db.py`
- [Reference data](https://github.com/kirtom/nepalvideo/blob/main/src/nepal/reference.py): `src/nepal/reference.py`

### Other components

- **Operator**
- **Raw media**
- **SRTM and GeoNames**
- **Documentary and short**

## Connections

- Operator → CLI: runs stages
- Raw media → S01 Probe: probes files
- CLI → S01 Probe: dispatches
- S01 Probe → Asset manifest: builds inventory
- S01 Probe → Chapter grouping: groups chapters
- S01 Probe → Lens FOV: solves lens
- S01 Probe → Clock offsets: solves offsets
- S01 Probe → Pipeline database: records results
- CLI → S02 Spine: dispatches
- S02 Spine → GPS track: builds track
- S02 Spine → Elevation: adds elevation
- S02 Spine → Place names: resolves places
- S02 Spine → Act boundaries: sets acts
- S02 Spine → Telegram story: processes messages
- S02 Spine → Music map: maps music
- S02 Spine → Reference data: reads datasets
- Reference data → SRTM and GeoNames: fetches
- S02 Spine → Pipeline database: records story
- CLI → S03 Process: dispatches
- S03 Process → Proxy and views: creates proxies
- S03 Process → Shot detection: detects shots
- S03 Process → Clip metrics: measures shots
- S03 Process → Audio analysis: analyzes audio
- S03 Process → Speech transcription: transcribes speech
- S03 Process → Quality gate: gates quality
- S03 Process → Pipeline database: records processing
- CLI → S04 Semantic: dispatches
- S04 Semantic → S05 Score and cut: semantic inputs
- CLI → S05 Score and cut: dispatches
- S05 Score and cut → Shortlist: ranks candidates
- S05 Score and cut → Assembly: selects edit
- Assembly → Draft render: builds draft
- Draft render → Documentary and short: produces