# gondchawarswaraj45/moviemaxx architecture

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

- Interactive diagram: https://gitdiagram.com/gondchawarswaraj45/moviemaxx
- Repository: https://github.com/gondchawarswaraj45/moviemaxx

## Overview

Moviemaxx is a conversational Bollywood movie recommender. A user submits a query through the web UI; the API delegates processing to a coordinator, which audits safety, retrieves and ranks movies using graph and vector signals, then adds streaming and social-watch guidance for the response. Catalog ingestion, recommendation history, and the graph explorer are supporting capabilities. Agent wiring and the Graph RAG scoring path are visible in sampled source; some API routes and agent internals were not sampled, so uncertain links are omitted.

Main entry points: [`app.py`](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/app.py) (FastAPI), [`agents/coordinator_agent.py`](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/coordinator_agent.py) (Coordinator Agent), [`movie_graph.py`](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/movie_graph.py) (Movie Graph Ops), [`rag/graph_rag.py`](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/graph_rag.py) (Graph RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web UI<br/>[app.js]"]
  node_api["FastAPI<br/>[app.py]"]
  node_graph_page["Graph Explorer<br/>[graph.html]"]
end

subgraph group_orchestration["Agent Orchestration"]
  node_coordinator["Coordinator Agent"]
  node_guardrail_agent["Guardrail Agent<br/>[guardrail_agent.py]"]
  node_guardrail_engine["P2 Guardrails<br/>[p2_guardrails.py]"]
  node_recommender_agent["Recommender Agent"]
  node_streaming_agent["Streaming Agent<br/>[streaming_agent.py]"]
  node_planner_agent["Watch Planner"]
end

subgraph group_recommendation["Recommendation"]
  node_graph_rag["Graph RAG<br/>[graph_rag.py]"]
  node_chunker["Relative Chunker<br/>[chunker.py]"]
  node_embedder["Cohere Embedder<br/>[cohere_embedder.py]"]
end

subgraph group_catalog["Catalog and Data"]
  node_catalog_ops["Movie Graph Ops<br/>[movie_graph.py]"]
  node_movie_data["Movie Catalog"]
  node_metadata["Catalog Metadata"]
  node_skills["Agent Skills<br/>[agent_skills.py]"]
  node_mcp["Neo4j MCP Client"]
end

node_viewer(("Viewer"))
node_cohere{{"Cohere API"}}
node_neo4j[("Neo4j")]

node_viewer -->|"submits query"| node_web
node_web -->|"calls API"| node_api
node_api -->|"processes query"| node_coordinator
node_coordinator -->|"audits prompt"| node_guardrail_agent
node_guardrail_agent -->|"evaluates prompt"| node_guardrail_engine
node_coordinator -->|"requests candidates"| node_recommender_agent
node_recommender_agent -->|"gets recommendations"| node_graph_rag
node_graph_rag -->|"searches graph"| node_catalog_ops
node_catalog_ops -->|"queries catalog"| node_neo4j
node_graph_rag -->|"chunks movie data"| node_chunker
node_graph_rag -->|"embeds query"| node_embedder
node_embedder -->|"requests embeddings"| node_cohere
node_coordinator -->|"gets platform guidance"| node_streaming_agent
node_coordinator -->|"plans watch context"| node_planner_agent
node_coordinator -->|"returns response"| node_api
node_api -->|"serves response"| node_web
node_viewer -->|"requests catalog sync"| node_api
node_api -->|"starts import"| node_catalog_ops
node_catalog_ops -->|"loads records"| node_movie_data
node_catalog_ops -->|"writes catalog"| node_neo4j
node_viewer -->|"opens explorer"| node_graph_page
node_graph_page -->|"requests graph data"| node_api
node_api -->|"reads graph data"| node_neo4j
node_api -->|"serves metadata"| node_metadata
node_api -->|"lists skill metadata"| node_skills
node_skills -->|"runs safety skill"| node_guardrail_engine
node_skills -->|"runs graph search"| node_catalog_ops
node_skills -->|"runs vector search"| node_graph_rag
node_mcp -.->|"queries or writes"| node_neo4j

click node_web "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/static/app.js"
click node_api "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/app.py"
click node_graph_page "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/static/graph.html"
click node_coordinator "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/coordinator_agent.py"
click node_guardrail_agent "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/guardrail_agent.py"
click node_guardrail_engine "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/guardrails/p2_guardrails.py"
click node_recommender_agent "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/recommender_agent.py"
click node_streaming_agent "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/streaming_agent.py"
click node_planner_agent "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/watch_planner_agent.py"
click node_graph_rag "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/graph_rag.py"
click node_chunker "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/chunker.py"
click node_embedder "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/cohere_embedder.py"
click node_catalog_ops "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/movie_graph.py"
click node_movie_data "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/expanded_dataset.py"
click node_metadata "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/metadata/catalog_metadata.py"
click node_skills "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/metadata/agent_skills.py"
click node_mcp "https://github.com/gondchawarswaraj45/moviemaxx/blob/main/mcp/neo4j_mcp_client.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_web,node_api,node_graph_page,node_viewer toneBlue
class node_coordinator,node_guardrail_agent,node_guardrail_engine,node_recommender_agent,node_streaming_agent,node_planner_agent,node_neo4j toneAmber
class node_graph_rag,node_chunker,node_embedder,node_cohere toneMint
class node_catalog_ops,node_movie_data,node_metadata,node_skills,node_mcp toneRose
```

## Components

### User Experience

- [Web UI](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/static/app.js): `static/app.js`
- [FastAPI](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/app.py): `app.py`
- [Graph Explorer](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/static/graph.html): `static/graph.html`

### Agent Orchestration

- [Coordinator Agent](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/coordinator_agent.py): `agents/coordinator_agent.py`
- [Guardrail Agent](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/guardrail_agent.py): `agents/guardrail_agent.py`
- [P2 Guardrails](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/guardrails/p2_guardrails.py): `guardrails/p2_guardrails.py`
- [Recommender Agent](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/recommender_agent.py): `agents/recommender_agent.py`
- [Streaming Agent](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/streaming_agent.py): `agents/streaming_agent.py`
- [Watch Planner](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/agents/watch_planner_agent.py): `agents/watch_planner_agent.py`

### Recommendation

- [Graph RAG](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/graph_rag.py): `rag/graph_rag.py`
- [Relative Chunker](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/chunker.py): `rag/chunker.py`
- [Cohere Embedder](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/rag/cohere_embedder.py): `rag/cohere_embedder.py`

### Catalog and Data

- [Movie Graph Ops](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/movie_graph.py): `movie_graph.py`
- [Movie Catalog](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/expanded_dataset.py): `expanded_dataset.py`
- [Catalog Metadata](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/metadata/catalog_metadata.py): `metadata/catalog_metadata.py`
- [Agent Skills](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/metadata/agent_skills.py): `metadata/agent_skills.py`
- [Neo4j MCP Client](https://github.com/gondchawarswaraj45/moviemaxx/blob/main/mcp/neo4j_mcp_client.py): `mcp/neo4j_mcp_client.py`

### Other components

- **Viewer**
- **Cohere API**
- **Neo4j**

## Connections

- Viewer → Web UI: submits query
- Web UI → FastAPI: calls API
- FastAPI → Coordinator Agent: processes query
- Coordinator Agent → Guardrail Agent: audits prompt
- Guardrail Agent → P2 Guardrails: evaluates prompt
- Coordinator Agent → Recommender Agent: requests candidates
- Recommender Agent → Graph RAG: gets recommendations
- Graph RAG → Movie Graph Ops: searches graph
- Movie Graph Ops → Neo4j: queries catalog
- Graph RAG → Relative Chunker: chunks movie data
- Graph RAG → Cohere Embedder: embeds query
- Cohere Embedder → Cohere API: requests embeddings
- Coordinator Agent → Streaming Agent: gets platform guidance
- Coordinator Agent → Watch Planner: plans watch context
- Coordinator Agent → FastAPI: returns response
- FastAPI → Web UI: serves response
- Viewer → FastAPI: requests catalog sync
- FastAPI → Movie Graph Ops: starts import
- Movie Graph Ops → Movie Catalog: loads records
- Movie Graph Ops → Neo4j: writes catalog
- Viewer → Graph Explorer: opens explorer
- Graph Explorer → FastAPI: requests graph data
- FastAPI → Neo4j: reads graph data
- FastAPI → Catalog Metadata: serves metadata
- FastAPI → Agent Skills: lists skill metadata
- Agent Skills → P2 Guardrails: runs safety skill
- Agent Skills → Movie Graph Ops: runs graph search
- Agent Skills → Graph RAG: runs vector search
- Neo4j MCP Client → Neo4j: queries or writes