# profgaurav/take-two-crew architecture

> Architecture diagram of the GitHub repository profgaurav/take-two-crew, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/profgaurav/take-two-crew
- Repository: https://github.com/profgaurav/take-two-crew

## Overview

Take Two Crew is a human-reviewed VFX quality-control portal for AI-generated video. Artists turn scripts into finalized scenes, generate and critique clips, then approve or reject them; rejection can trigger up to three refinement passes. Separate workflows support targeted frame fixes, project references, and ClickHouse-backed dashboard and performance analysis. The graph preserves those documented capabilities and the sampled agent, media, telemetry, and data layers; some connections for unsampled page implementations rely on the README or SOURCE INDEX rather than inspected function bodies.

Main entry points: [`data_layer/clickhouse.py`](https://github.com/profgaurav/take-two-crew/blob/main/data_layer/clickhouse.py) (ClickHouse Data Layer), [`apps/webapp/webapp/webapp.py`](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/webapp.py) (Portal Routes), [`agents/orchestrator.py`](https://github.com/profgaurav/take-two-crew/blob/main/agents/orchestrator.py) (Pipeline Orchestrator), [`video_gen/veo_client.py`](https://github.com/profgaurav/take-two-crew/blob/main/video_gen/veo_client.py) (Veo Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Artist Portal"]
  node_portal_app["Portal Routes<br/>[webapp.py]"]
  node_scene_ui["Scene Creation<br/>[scene_creation.py]"]
  node_generation_ui["Generation Console<br/>[generation.py]"]
  node_escalation_ui["Escalation Console<br/>[escalation.py]"]
  node_dashboard_ui["Dashboard<br/>[dashboard.py]"]
  node_performance_ui["Performance Tab<br/>[performance.py]"]
  node_references_ui["References Library<br/>[references.py]"]
  node_ui_primitives["UI Primitives<br/>[primitives.py]"]
  node_ui_state["Portal State<br/>[state.py]"]
  node_mock_data["Static Portal Data<br/>[mock_data.py]"]
end

subgraph group_workflow["Agent Workflow"]
  node_scene_agent["Scene Agent<br/>[scene_agent.py]"]
  node_brief_agent["Brief Agent<br/>[brief_agent.py]"]
  node_orchestrator["Pipeline Orchestrator<br/>[orchestrator.py]"]
  node_critique_agent["Critique Agent<br/>[critique_agent.py]"]
  node_refinement_agent["Refinement Agent"]
  node_frame_fix["Frame Fix Pipeline"]
end

subgraph group_media["Media Services"]
  node_veo_client["Veo Client<br/>[veo_client.py]"]
  node_embedding_client["Embedding Client"]
end

subgraph group_ops["Data and Analytics"]
  node_clickhouse[("ClickHouse Data Layer<br/>[clickhouse.py]")]
  node_telemetry["Pipeline Telemetry<br/>[telemetry.py]"]
end

node_artist(("VFX Artist"))
node_gemini{{"Gemini / Vertex AI"}}
node_veo_service{{"Veo / Vertex AI"}}
node_gcs[("Google Cloud Storage")]

node_artist -->|"uses portal"| node_portal_app
node_portal_app -->|"routes to"| node_scene_ui
node_portal_app -->|"routes to"| node_generation_ui
node_portal_app -->|"routes to"| node_escalation_ui
node_portal_app -->|"routes to"| node_dashboard_ui
node_portal_app -->|"routes to"| node_performance_ui
node_portal_app -->|"routes to"| node_references_ui
node_scene_ui -->|"breaks into scenes"| node_scene_agent
node_scene_ui -->|"stores scenes"| node_clickhouse
node_generation_ui -->|"runs pipeline"| node_orchestrator
node_generation_ui -->|"records reviews"| node_clickhouse
node_escalation_ui -->|"requests frame fix"| node_frame_fix
node_escalation_ui -->|"submits review"| node_orchestrator
node_escalation_ui -->|"reads clip data"| node_clickhouse
node_dashboard_ui -->|"reads summaries"| node_clickhouse
node_performance_ui -->|"reads metrics"| node_clickhouse
node_performance_ui -->|"embeds media"| node_embedding_client
node_references_ui -->|"manages subjects"| node_clickhouse
node_references_ui -->|"embeds references"| node_embedding_client
node_references_ui -->|"loads media"| node_veo_client
node_scene_ui -->|"renders with"| node_ui_primitives
node_ui_state -.->|"authenticates portal"| node_clickhouse
node_orchestrator -->|"creates brief"| node_brief_agent
node_orchestrator -->|"generates clip"| node_veo_client
node_orchestrator -->|"critiques clip"| node_critique_agent
node_orchestrator -->|"refines rejected clip"| node_refinement_agent
node_orchestrator -->|"persists pipeline"| node_clickhouse
node_scene_agent -.->|"analyzes script"| node_gemini
node_brief_agent -->|"builds brief"| node_gemini
node_critique_agent -->|"evaluates clip"| node_gemini
node_refinement_agent -.->|"revises brief"| node_gemini
node_veo_client -->|"renders video"| node_veo_service
node_veo_client -->|"writes clips"| node_gcs
node_embedding_client -->|"creates embeddings"| node_gemini
node_embedding_client -->|"uses MIME helper"| node_veo_client
node_frame_fix -->|"uses clip media"| node_veo_client
node_frame_fix -->|"records fixes"| node_clickhouse
node_brief_agent -->|"logs calls"| node_telemetry
node_critique_agent -->|"logs calls"| node_telemetry
node_telemetry -->|"writes events"| node_clickhouse
node_clickhouse -.->|"stores media references"| node_gcs

click node_portal_app "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/webapp.py"
click node_scene_ui "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/scene_creation.py"
click node_generation_ui "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/generation.py"
click node_escalation_ui "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/escalation.py"
click node_dashboard_ui "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/dashboard.py"
click node_performance_ui "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/performance.py"
click node_references_ui "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/references.py"
click node_ui_primitives "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/components/primitives.py"
click node_ui_state "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/state.py"
click node_mock_data "https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/mock_data.py"
click node_scene_agent "https://github.com/profgaurav/take-two-crew/blob/main/agents/scene_agent.py"
click node_brief_agent "https://github.com/profgaurav/take-two-crew/blob/main/agents/brief_agent.py"
click node_orchestrator "https://github.com/profgaurav/take-two-crew/blob/main/agents/orchestrator.py"
click node_critique_agent "https://github.com/profgaurav/take-two-crew/blob/main/agents/critique_agent.py"
click node_refinement_agent "https://github.com/profgaurav/take-two-crew/blob/main/agents/refinement_agent.py"
click node_frame_fix "https://github.com/profgaurav/take-two-crew/blob/main/agents/frame_fix_pipeline.py"
click node_veo_client "https://github.com/profgaurav/take-two-crew/blob/main/video_gen/veo_client.py"
click node_embedding_client "https://github.com/profgaurav/take-two-crew/blob/main/video_gen/embedding_client.py"
click node_clickhouse "https://github.com/profgaurav/take-two-crew/blob/main/data_layer/clickhouse.py"
click node_telemetry "https://github.com/profgaurav/take-two-crew/blob/main/data_layer/telemetry.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_portal_app,node_scene_ui,node_generation_ui,node_escalation_ui,node_dashboard_ui,node_performance_ui,node_references_ui,node_ui_primitives,node_ui_state,node_mock_data toneBlue
class node_scene_agent,node_brief_agent,node_orchestrator,node_critique_agent,node_refinement_agent,node_frame_fix,node_gcs toneAmber
class node_veo_client,node_embedding_client toneMint
class node_clickhouse,node_telemetry toneRose
class node_artist,node_gemini,node_veo_service toneIndigo
```

## Components

### Artist Portal

- [Portal Routes](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/webapp.py): `apps/webapp/webapp/webapp.py`
- [Scene Creation](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/scene_creation.py): `apps/webapp/webapp/pages/scene_creation.py`
- [Generation Console](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/generation.py): `apps/webapp/webapp/pages/generation.py`
- [Escalation Console](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/escalation.py): `apps/webapp/webapp/pages/escalation.py`
- [Dashboard](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/dashboard.py): `apps/webapp/webapp/pages/dashboard.py`
- [Performance Tab](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/performance.py): `apps/webapp/webapp/pages/performance.py`
- [References Library](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/pages/references.py): `apps/webapp/webapp/pages/references.py`
- [UI Primitives](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/components/primitives.py): `apps/webapp/webapp/components/primitives.py`
- [Portal State](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/state.py): `apps/webapp/webapp/state.py`
- [Static Portal Data](https://github.com/profgaurav/take-two-crew/blob/main/apps/webapp/webapp/mock_data.py): `apps/webapp/webapp/mock_data.py`

### Agent Workflow

- [Scene Agent](https://github.com/profgaurav/take-two-crew/blob/main/agents/scene_agent.py): `agents/scene_agent.py`
- [Brief Agent](https://github.com/profgaurav/take-two-crew/blob/main/agents/brief_agent.py): `agents/brief_agent.py`
- [Pipeline Orchestrator](https://github.com/profgaurav/take-two-crew/blob/main/agents/orchestrator.py): `agents/orchestrator.py`
- [Critique Agent](https://github.com/profgaurav/take-two-crew/blob/main/agents/critique_agent.py): `agents/critique_agent.py`
- [Refinement Agent](https://github.com/profgaurav/take-two-crew/blob/main/agents/refinement_agent.py): `agents/refinement_agent.py`
- [Frame Fix Pipeline](https://github.com/profgaurav/take-two-crew/blob/main/agents/frame_fix_pipeline.py): `agents/frame_fix_pipeline.py`

### Media Services

- [Veo Client](https://github.com/profgaurav/take-two-crew/blob/main/video_gen/veo_client.py): `video_gen/veo_client.py`
- [Embedding Client](https://github.com/profgaurav/take-two-crew/blob/main/video_gen/embedding_client.py): `video_gen/embedding_client.py`

### Data and Analytics

- [ClickHouse Data Layer](https://github.com/profgaurav/take-two-crew/blob/main/data_layer/clickhouse.py): `data_layer/clickhouse.py`
- [Pipeline Telemetry](https://github.com/profgaurav/take-two-crew/blob/main/data_layer/telemetry.py): `data_layer/telemetry.py`

### Other components

- **VFX Artist**
- **Gemini / Vertex AI**
- **Veo / Vertex AI**
- **Google Cloud Storage**

## Connections

- VFX Artist → Portal Routes: uses portal (evidence: `README.md`)
- Portal Routes → Scene Creation: routes to (evidence: `apps/webapp/webapp/webapp.py`)
- Portal Routes → Generation Console: routes to (evidence: `apps/webapp/webapp/webapp.py`)
- Portal Routes → Escalation Console: routes to (evidence: `apps/webapp/webapp/webapp.py`)
- Portal Routes → Dashboard: routes to (evidence: `apps/webapp/webapp/webapp.py`)
- Portal Routes → Performance Tab: routes to (evidence: `apps/webapp/webapp/webapp.py`)
- Portal Routes → References Library: routes to (evidence: `apps/webapp/webapp/webapp.py`)
- Scene Creation → Scene Agent: breaks into scenes (evidence: `apps/webapp/webapp/pages/scene_creation.py`)
- Scene Creation → ClickHouse Data Layer: stores scenes (evidence: `apps/webapp/webapp/pages/scene_creation.py`)
- Generation Console → Pipeline Orchestrator: runs pipeline (evidence: `apps/webapp/webapp/pages/generation.py`)
- Generation Console → ClickHouse Data Layer: records reviews (evidence: `apps/webapp/webapp/pages/generation.py`)
- Escalation Console → Frame Fix Pipeline: requests frame fix (evidence: `apps/webapp/webapp/pages/escalation.py`)
- Escalation Console → Pipeline Orchestrator: submits review (evidence: `apps/webapp/webapp/pages/escalation.py`)
- Escalation Console → ClickHouse Data Layer: reads clip data (evidence: `apps/webapp/webapp/pages/escalation.py`)
- Dashboard → ClickHouse Data Layer: reads summaries (evidence: `apps/webapp/webapp/pages/dashboard.py`)
- Performance Tab → ClickHouse Data Layer: reads metrics (evidence: `apps/webapp/webapp/pages/performance.py`)
- Performance Tab → Embedding Client: embeds media (evidence: `apps/webapp/webapp/pages/performance.py`)
- References Library → ClickHouse Data Layer: manages subjects (evidence: `apps/webapp/webapp/pages/references.py`)
- References Library → Embedding Client: embeds references (evidence: `apps/webapp/webapp/pages/references.py`)
- References Library → Veo Client: loads media (evidence: `apps/webapp/webapp/pages/references.py`)
- Scene Creation → UI Primitives: renders with (evidence: `apps/webapp/webapp/pages/scene_creation.py`)
- Portal State → ClickHouse Data Layer: authenticates portal
- Pipeline Orchestrator → Brief Agent: creates brief (evidence: `agents/orchestrator.py`)
- Pipeline Orchestrator → Veo Client: generates clip (evidence: `agents/orchestrator.py`)
- Pipeline Orchestrator → Critique Agent: critiques clip (evidence: `agents/orchestrator.py`)
- Pipeline Orchestrator → Refinement Agent: refines rejected clip (evidence: `agents/orchestrator.py`)
- Pipeline Orchestrator → ClickHouse Data Layer: persists pipeline (evidence: `agents/orchestrator.py`)
- Scene Agent → Gemini / Vertex AI: analyzes script (evidence: `README.md`)
- Brief Agent → Gemini / Vertex AI: builds brief (evidence: `agents/brief_agent.py`)
- Critique Agent → Gemini / Vertex AI: evaluates clip (evidence: `agents/critique_agent.py`)
- Refinement Agent → Gemini / Vertex AI: revises brief
- Veo Client → Veo / Vertex AI: renders video (evidence: `README.md`)
- Veo Client → Google Cloud Storage: writes clips (evidence: `video_gen/veo_client.py`)
- Embedding Client → Gemini / Vertex AI: creates embeddings (evidence: `video_gen/embedding_client.py`)
- Embedding Client → Veo Client: uses MIME helper (evidence: `video_gen/embedding_client.py`)
- Frame Fix Pipeline → Veo Client: uses clip media (evidence: `agents/frame_fix_pipeline.py`)
- Frame Fix Pipeline → ClickHouse Data Layer: records fixes (evidence: `agents/frame_fix_pipeline.py`)
- Brief Agent → Pipeline Telemetry: logs calls (evidence: `agents/brief_agent.py`)
- Critique Agent → Pipeline Telemetry: logs calls (evidence: `agents/critique_agent.py`)
- Pipeline Telemetry → ClickHouse Data Layer: writes events (evidence: `data_layer/telemetry.py`)
- ClickHouse Data Layer → Google Cloud Storage: stores media references