# vishnureddy1705/hacknex architecture

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

- Interactive diagram: https://gitdiagram.com/vishnureddy1705/hacknex
- Repository: https://github.com/vishnureddy1705/hacknex

## Overview

TimeSense AI turns uploaded video into persistent object tracks, semantic events, and a temporal relationship graph; users can inspect the analysis or ask timestamp-grounded questions and seek to supporting video. The documented pipeline establishes the major processing stages, while the source index and excerpts support selected implementation links. Some internals, including detector and tracker behavior and parts of the API orchestration, were not sampled, so uncertain connections are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/App.tsx) (Dashboard shell), [`backend/app/services/video_processor.py`](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/video_processor.py) (Video processor), [`backend/app/api/questions.py`](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/questions.py) (Question API), [`frontend/src/services/api.ts`](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/services/api.ts) (REST client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard"]
  node_app["Dashboard shell<br/>[App.tsx]"]
  node_api_client["REST client<br/>[api.ts]"]
end

subgraph group_ingest["Video processing"]
  node_upload["Video upload API<br/>[videos.py]"]
  node_processor["Video processor<br/>[video_processor.py]"]
  node_detector["Object detection<br/>[detector.py]"]
  node_tracker["Identity tracking<br/>[tracker.py]"]
  node_events["Event detection<br/>[event_detector.py]"]
end

subgraph group_reason["Temporal Q&amp;A"]
  node_temporal["Temporal graph<br/>[temporal_engine.py]"]
  node_question_api["Question API<br/>[questions.py]"]
  node_parser["Question parser<br/>[question_parser.py]"]
  node_retriever["Evidence retrieval"]
  node_answer["Answer generation"]
  node_vlm["Optional VLM<br/>[vlm_service.py]"]
  node_timeline_api["Events API<br/>[events.py]"]
  node_timestamps["Timestamp utilities<br/>[timestamps.py]"]
end

subgraph group_state["Persistence"]
  node_database[("SQLite data store<br/>[database.py]")]
end

subgraph group_presentation["Playback and views"]
  node_video_player["Video player<br/>[VideoPlayer.tsx]"]
  node_ask_page["Ask video<br/>[AskVideoPage.tsx]"]
  node_timeline_page["Event timeline"]
  node_entities_page["Entity browser<br/>[EntitiesPage.tsx]"]
  node_overview_page["Video overview<br/>[OverviewPage.tsx]"]
  node_analysis_page["Video analysis"]
end

node_user(("Video analyst"))

node_user -->|"uses"| node_app
node_app -->|"requests data"| node_api_client
node_api_client -->|"uploads video"| node_upload
node_upload -->|"queues processing"| node_processor
node_processor -->|"tracks objects"| node_tracker
node_processor -->|"extracts events"| node_events
node_processor -->|"builds graph"| node_temporal
node_processor -->|"detects objects"| node_detector
node_processor -->|"persists analysis"| node_database
node_temporal -->|"stores relationships"| node_database
node_question_api -->|"parses question"| node_parser
node_question_api -->|"retrieves evidence"| node_retriever
node_question_api -->|"generates answer"| node_answer
node_question_api -.->|"optionally verifies"| node_vlm
node_question_api -.->|"records Q&amp;A"| node_database
node_retriever -->|"reads evidence"| node_database
node_answer -->|"formats times"| node_timestamps
node_retriever -->|"formats evidence times"| node_timestamps
node_timeline_api -->|"reads events"| node_database
node_app -->|"shows Q&amp;A"| node_ask_page
node_app -->|"shows timeline"| node_timeline_page
node_app -->|"shows entities"| node_entities_page
node_app -->|"shows overview"| node_overview_page
node_app -->|"shows analysis"| node_analysis_page
node_ask_page -->|"submits question"| node_api_client
node_ask_page -.->|"seeks evidence"| node_video_player
node_timeline_page -->|"shows playback"| node_video_player
node_analysis_page -->|"shows playback"| node_video_player
node_overview_page -->|"loads video data"| node_api_client
node_video_player -->|"streams video"| node_api_client
node_api_client -->|"asks question"| node_question_api

click node_app "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/services/api.ts"
click node_upload "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/videos.py"
click node_processor "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/video_processor.py"
click node_detector "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/detector.py"
click node_tracker "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/tracker.py"
click node_events "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/event_detector.py"
click node_temporal "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/temporal_engine.py"
click node_question_api "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/questions.py"
click node_parser "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/question_parser.py"
click node_retriever "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/evidence_retriever.py"
click node_answer "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/answer_generator.py"
click node_vlm "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/vlm_service.py"
click node_database "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/database.py"
click node_timeline_api "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/events.py"
click node_video_player "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/components/VideoPlayer.tsx"
click node_ask_page "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/AskVideoPage.tsx"
click node_timeline_page "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/EventTimelinePage.tsx"
click node_entities_page "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/EntitiesPage.tsx"
click node_overview_page "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/OverviewPage.tsx"
click node_analysis_page "https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/VideoAnalysisPage.tsx"
click node_timestamps "https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/utils/timestamps.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_app,node_api_client toneBlue
class node_upload,node_processor,node_detector,node_tracker,node_events toneAmber
class node_temporal,node_question_api,node_parser,node_retriever,node_answer,node_vlm,node_timeline_api,node_timestamps toneMint
class node_database toneRose
class node_video_player,node_ask_page,node_timeline_page,node_entities_page,node_overview_page,node_analysis_page,node_user toneIndigo
```

## Components

### Dashboard

- [Dashboard shell](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [REST client](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Video processing

- [Video upload API](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/videos.py): `backend/app/api/videos.py`
- [Video processor](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/video_processor.py): `backend/app/services/video_processor.py`
- [Object detection](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/detector.py): `backend/app/services/detector.py`
- [Identity tracking](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/tracker.py): `backend/app/services/tracker.py`
- [Event detection](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/event_detector.py): `backend/app/services/event_detector.py`

### Temporal Q&A

- [Temporal graph](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/temporal_engine.py): `backend/app/services/temporal_engine.py`
- [Question API](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/questions.py): `backend/app/api/questions.py`
- [Question parser](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/question_parser.py): `backend/app/services/question_parser.py`
- [Evidence retrieval](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/evidence_retriever.py): `backend/app/services/evidence_retriever.py`
- [Answer generation](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/answer_generator.py): `backend/app/services/answer_generator.py`
- [Optional VLM](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/services/vlm_service.py): `backend/app/services/vlm_service.py`
- [Events API](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/api/events.py): `backend/app/api/events.py`
- [Timestamp utilities](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/utils/timestamps.py): `backend/app/utils/timestamps.py`

### Persistence

- [SQLite data store](https://github.com/vishnureddy1705/hacknex/blob/main/backend/app/database.py): `backend/app/database.py`

### Playback and views

- [Video player](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/components/VideoPlayer.tsx): `frontend/src/components/VideoPlayer.tsx`
- [Ask video](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/AskVideoPage.tsx): `frontend/src/pages/AskVideoPage.tsx`
- [Event timeline](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/EventTimelinePage.tsx): `frontend/src/pages/EventTimelinePage.tsx`
- [Entity browser](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/EntitiesPage.tsx): `frontend/src/pages/EntitiesPage.tsx`
- [Video overview](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/OverviewPage.tsx): `frontend/src/pages/OverviewPage.tsx`
- [Video analysis](https://github.com/vishnureddy1705/hacknex/blob/main/frontend/src/pages/VideoAnalysisPage.tsx): `frontend/src/pages/VideoAnalysisPage.tsx`

### Other components

- **Video analyst**

## Connections

- Video analyst → Dashboard shell: uses
- Dashboard shell → REST client: requests data (evidence: `frontend/src/App.tsx`)
- REST client → Video upload API: uploads video (evidence: `frontend/src/services/api.ts`)
- Video upload API → Video processor: queues processing (evidence: `backend/app/api/videos.py`)
- Video processor → Identity tracking: tracks objects (evidence: `backend/app/services/video_processor.py`)
- Video processor → Event detection: extracts events (evidence: `backend/app/services/video_processor.py`)
- Video processor → Temporal graph: builds graph (evidence: `backend/app/services/video_processor.py`)
- Video processor → Object detection: detects objects
- Video processor → SQLite data store: persists analysis (evidence: `backend/app/services/video_processor.py`)
- Temporal graph → SQLite data store: stores relationships (evidence: `backend/app/services/temporal_engine.py`)
- Question API → Question parser: parses question (evidence: `backend/app/api/questions.py`)
- Question API → Evidence retrieval: retrieves evidence (evidence: `backend/app/api/questions.py`)
- Question API → Answer generation: generates answer (evidence: `backend/app/api/questions.py`)
- Question API → Optional VLM: optionally verifies (evidence: `backend/app/api/questions.py`)
- Question API → SQLite data store: records Q&A (evidence: `backend/app/api/questions.py`)
- Evidence retrieval → SQLite data store: reads evidence (evidence: `backend/app/services/evidence_retriever.py`)
- Answer generation → Timestamp utilities: formats times (evidence: `backend/app/services/answer_generator.py`)
- Evidence retrieval → Timestamp utilities: formats evidence times (evidence: `backend/app/services/evidence_retriever.py`)
- Events API → SQLite data store: reads events (evidence: `backend/app/api/events.py`)
- Dashboard shell → Ask video: shows Q&A (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Event timeline: shows timeline (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Entity browser: shows entities (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Video overview: shows overview (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Video analysis: shows analysis (evidence: `frontend/src/App.tsx`)
- Ask video → REST client: submits question (evidence: `frontend/src/pages/AskVideoPage.tsx`)
- Ask video → Video player: seeks evidence (evidence: `frontend/src/pages/AskVideoPage.tsx`)
- Event timeline → Video player: shows playback (evidence: `frontend/src/pages/EventTimelinePage.tsx`)
- Video analysis → Video player: shows playback (evidence: `frontend/src/pages/VideoAnalysisPage.tsx`)
- Video overview → REST client: loads video data (evidence: `frontend/src/pages/OverviewPage.tsx`)
- Video player → REST client: streams video (evidence: `frontend/src/components/VideoPlayer.tsx`)
- REST client → Question API: asks question (evidence: `frontend/src/services/api.ts`)
