# bouchta65/navi-pilot architecture

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

- Interactive diagram: https://gitdiagram.com/bouchta65/navi-pilot
- Repository: https://github.com/bouchta65/navi-pilot

## Overview

NAVI is a command-center application for configuring, generating, rendering, and publishing short-form videos. The principal workflow starts with an operator using the React Operations screen to create a project; the backend runs its Master Video Plan workflow through queued jobs, produces narration and timed captions, assembles the video, and can upload it to YouTube. Configuration, analytics, authentication, and project progress via WebSocket are additional product capabilities. Several workflow implementations are unsampled, so their documented connections are identified as such rather than inferred from filenames.

Main entry points: [`backend/app/workers/master_stages.py`](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/master_stages.py) (Master plan stages), [`frontend/src/pages/LiveDashboard.tsx`](https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/pages/LiveDashboard.tsx) (Operations console), [`frontend/src/api/client.ts`](https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/api/client.ts) (API client), [`backend/app/services/video/video_assembler.py`](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/video_assembler.py) (Video assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator_ui["Operator interface"]
  node_command_center["Operations console<br/>[LiveDashboard.tsx]"]
  node_statistics_ui["Statistics view<br/>[Statistics.tsx]"]
  node_frontend_api["API client<br/>[client.ts]"]
end

subgraph group_api_domain["API and configuration"]
  node_project_api["Project API<br/>[projects.py]"]
  node_configuration_api["Configuration API<br/>[configuration.py]"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
  node_auth_security["Session security<br/>[security.py]"]
  node_configuration_service["Configuration service<br/>[configuration.py]"]
  node_database[("PostgreSQL records<br/>[database.py]")]
  node_project_socket["Project progress socket<br/>[projectSocket.ts]"]
end

subgraph group_job_pipeline["Video job pipeline"]
  node_project_worker["Project worker<br/>[project_tasks.py]"]
  node_workflow["Master workflow stages<br/>[workflow.py]"]
  node_master_stages["Master plan stages<br/>[master_stages.py]"]
  node_keyword_script["AI planning"]
  node_research["Research"]
  node_voice["Narration and timing<br/>[tts_service.py]"]
  node_captions["Caption rendering<br/>[engine.py]"]
  node_subtitle_service["Subtitle timing"]
  node_video_render["Video assembly<br/>[video_assembler.py]"]
end

subgraph group_media_integrations["Media and publishing"]
  node_media_matching["Media matching"]
  node_storage["Media storage<br/>[storage.py]"]
  node_youtube["YouTube publishing<br/>[upload_service.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_command_center
node_command_center -->|"calls API"| node_frontend_api
node_frontend_api -->|"sends requests"| node_project_api
node_project_api -.->|"queues jobs"| node_project_worker
node_project_worker -->|"runs workflow"| node_workflow
node_workflow -.->|"dispatches stages"| node_master_stages
node_operator -->|"sets configuration"| node_configuration_api
node_configuration_api -.->|"loads and saves"| node_configuration_service
node_configuration_service -->|"persists settings"| node_database
node_frontend_api -->|"authenticates"| node_auth_security
node_master_stages -.->|"requests AI planning"| node_keyword_script
node_master_stages -.->|"gathers sources"| node_research
node_master_stages -.->|"synthesizes narration"| node_voice
node_voice -->|"provides alignment"| node_subtitle_service
node_subtitle_service -.->|"supplies timed cues"| node_captions
node_master_stages -.->|"matches footage"| node_media_matching
node_master_stages -.->|"assembles render"| node_video_render
node_video_render -.->|"composites captions"| node_captions
node_video_render -.->|"stores output"| node_storage
node_master_stages -.->|"publishes video"| node_youtube
node_command_center -->|"tracks progress"| node_project_socket
node_operator -->|"views metrics"| node_statistics_ui
node_statistics_ui -.->|"requests analytics"| node_analytics_api

click node_command_center "https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/pages/LiveDashboard.tsx"
click node_statistics_ui "https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/pages/Statistics.tsx"
click node_frontend_api "https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/api/client.ts"
click node_project_api "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/api/projects.py"
click node_configuration_api "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/api/configuration.py"
click node_analytics_api "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/api/analytics.py"
click node_auth_security "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/core/security.py"
click node_configuration_service "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/configuration.py"
click node_database "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/core/database.py"
click node_project_worker "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/project_tasks.py"
click node_workflow "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/workflow.py"
click node_master_stages "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/master_stages.py"
click node_keyword_script "https://github.com/bouchta65/navi-pilot/tree/main/backend/app/services/gemini"
click node_research "https://github.com/bouchta65/navi-pilot/tree/main/backend/app/services/research"
click node_voice "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/audio/tts_service.py"
click node_captions "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/caption_engine/professional/engine.py"
click node_subtitle_service "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/subtitle_service.py"
click node_video_render "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/video_assembler.py"
click node_media_matching "https://github.com/bouchta65/navi-pilot/tree/main/backend/app/services/media"
click node_storage "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/storage.py"
click node_youtube "https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/youtube/upload_service.py"
click node_project_socket "https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/services/projectSocket.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_command_center,node_statistics_ui,node_frontend_api toneBlue
class node_project_api,node_configuration_api,node_analytics_api,node_auth_security,node_configuration_service,node_database,node_project_socket toneAmber
class node_project_worker,node_workflow,node_master_stages,node_keyword_script,node_research,node_voice,node_captions,node_subtitle_service,node_video_render toneMint
class node_media_matching,node_storage,node_youtube toneRose
class node_operator toneIndigo
```

## Components

### Operator interface

- [Operations console](https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/pages/LiveDashboard.tsx): `frontend/src/pages/LiveDashboard.tsx`
- [Statistics view](https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/pages/Statistics.tsx): `frontend/src/pages/Statistics.tsx`
- [API client](https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and configuration

- [Project API](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Configuration API](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/api/configuration.py): `backend/app/api/configuration.py`
- [Analytics API](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`
- [Session security](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Configuration service](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/configuration.py): `backend/app/services/configuration.py`
- [PostgreSQL records](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Project progress socket](https://github.com/bouchta65/navi-pilot/blob/main/frontend/src/services/projectSocket.ts): `frontend/src/services/projectSocket.ts`

### Video job pipeline

- [Project worker](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/project_tasks.py): `backend/app/workers/project_tasks.py`
- [Master workflow stages](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/workflow.py): `backend/app/workers/workflow.py`
- [Master plan stages](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/workers/master_stages.py): `backend/app/workers/master_stages.py`
- [AI planning](https://github.com/bouchta65/navi-pilot/tree/main/backend/app/services/gemini): `backend/app/services/gemini`
- [Research](https://github.com/bouchta65/navi-pilot/tree/main/backend/app/services/research): `backend/app/services/research`
- [Narration and timing](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/audio/tts_service.py): `backend/app/services/audio/tts_service.py`
- [Caption rendering](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/caption_engine/professional/engine.py): `backend/app/services/video/caption_engine/professional/engine.py`
- [Subtitle timing](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/subtitle_service.py): `backend/app/services/video/subtitle_service.py`
- [Video assembly](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/video/video_assembler.py): `backend/app/services/video/video_assembler.py`

### Media and publishing

- [Media matching](https://github.com/bouchta65/navi-pilot/tree/main/backend/app/services/media): `backend/app/services/media`
- [Media storage](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [YouTube publishing](https://github.com/bouchta65/navi-pilot/blob/main/backend/app/services/youtube/upload_service.py): `backend/app/services/youtube/upload_service.py`

### Other components

- **Operator**

## Connections

- Operator → Operations console: uses (evidence: `README.md`)
- Operations console → API client: calls API (evidence: `frontend/src/pages/LiveDashboard.tsx`)
- API client → Project API: sends requests (evidence: `README.md`)
- Project API → Project worker: queues jobs (evidence: `README.md`)
- Project worker → Master workflow stages: runs workflow (evidence: `backend/app/workers/project_tasks.py`)
- Master workflow stages → Master plan stages: dispatches stages
- Operator → Configuration API: sets configuration (evidence: `README.md`)
- Configuration API → Configuration service: loads and saves
- Configuration service → PostgreSQL records: persists settings (evidence: `backend/app/services/configuration.py`)
- API client → Session security: authenticates
- Master plan stages → AI planning: requests AI planning
- Master plan stages → Research: gathers sources
- Master plan stages → Narration and timing: synthesizes narration
- Narration and timing → Subtitle timing: provides alignment (evidence: `backend/app/services/video/subtitle_service.py`)
- Subtitle timing → Caption rendering: supplies timed cues
- Master plan stages → Media matching: matches footage
- Master plan stages → Video assembly: assembles render
- Video assembly → Caption rendering: composites captions
- Video assembly → Media storage: stores output
- Master plan stages → YouTube publishing: publishes video (evidence: `README.md`)
- Operations console → Project progress socket: tracks progress (evidence: `frontend/src/pages/LiveDashboard.tsx`)
- Operator → Statistics view: views metrics (evidence: `README.md`)
- Statistics view → Analytics API: requests analytics
