🎬 CineMetrics UI

CineMetrics is a next-generation, AI-powered box office telemetry, streaming performance, and social sentiment analytics dashboard designed for film studio executives and theatrical coordinators.

The application pairs a custom Gemini 1.5 Pro AI Agent (powered by Vertex AI) with a high-performance, columnar ClickHouse Cloud data warehouse. It translates natural language questions—such as "Should we pull Midnight Pulse?" or "What is the sentiment score trend of Neon Horizon?"—into sub-second SQL queries, delivering real-time theater recommendations and projected revenues.

---

🎨 Premium Cinematic Redesign

The user interface features a high-end, professional cinematic studio dashboard design (evoking an IMAX/A24 control console aesthetic).

Visual Features:

• Obsidian Canvas System: Built on a solid obsidian black canvas (#070709) with champagne gold accents (#dfb76c), emerald greens for successful runs, and ruby crimson for film risks.
• Prestige Typography: Google Display Serif font "Cinzel" for prestige branding alongside "Sora" for clean, tabular telemetry statistics.
• Ambient Projector Glow: Subtle gold spotlight lens-flares radiating from the top center to mimic theater projection light.
• Retro Countdown Loader: A vintage 35mm film leader countdown sequence (8 down to 2) with projector crosshairs, dust particle drift, and radar sweeps during cold starts.
• Widescreen Letterboxing: Executive briefs and reports are framed inside an immersive 2.39:1 widescreen scope.
• Micro-Animations: Staggered entrance animations and page transitions powered by Framer Motion.

---

🚀 Technology Stack

• Frontend Framework: React 19 + Vite (Hot Module Replacement)
• Visualizations & Charts: Recharts (with customized gold area gradients, bronze lines, and dual-axis bar gauges)
• Animations: Framer Motion
• Iconography: Lucide React
• Styling: Vanilla CSS (using modern, responsive glassmorphic design tokens)
• Hosting Integration: Google Cloud Run (REST API Server) + ClickHouse Cloud (Columnar DB)

---

⚙️ System Architecture & Workflow

1. Overall System Architecture

The client application acts as the control panel, querying a Spring Boot REST API which orchestrates tool use between Gemini 1.5 Pro (via Vertex AI) and a ClickHouse Cloud Columnar DB containing multi-million row telemetry datasets.

flowchart TB
    subgraph Client ["Client Side (React 19 + Vite)"]
        UI["Executive Dashboard UI"]
        AQ["CineMetrics AI Agent Chat"]
        AC["Real-Time Analytics (Recharts)"]
        SB["Morning Briefing Scope"]
        Router["React Router Router"]
    end

    subgraph ServiceLayer ["API & Operations Service"]
        APIClient["API Service (axios/fetch)"]
        Formatter["Content Preprocessor"]
    end

    subgraph Backend ["Remote API Server (Spring Boot on Google Cloud Run)"]
        Controller["Actuator & REST Controller"]
        GeminiAgent["Gemini 1.5 Pro AI Agent Orchestrator (Vertex AI)"]
    end

    subgraph Storage ["Database Cluster"]
        ClickHouse["ClickHouse Cloud (Columnar DB)"]
    end

    UI --> Router
    Router --> AQ & AC & SB
    AQ & AC & SB --> APIClient
    APIClient --> Controller
    Controller --> GeminiAgent
    GeminiAgent -->|Translates to SQL| ClickHouse
    ClickHouse -->|Sub-second Aggregations| GeminiAgent
    Controller -->|Structured JSON Response| APIClient
    APIClient --> Formatter
    Formatter -->|Highlight Telemetry & Bold Films| UI

Loading

2. Information Flow & Sequence Diagram

This diagram shows how a natural language question entered by a user is processed, converted to optimized SQL, executed, and rendered dynamically on the UI.

sequenceDiagram
    autonumber
    actor Executive as Studio Executive
    participant UI as React 19 Frontend
    participant Backend as Spring Boot Cloud Run
    participant Gemini as Gemini AI Vertex AI
    participant ClickHouse as ClickHouse Columnar DB

    Executive->>UI: Enter query (e.g., "Should we pull Film X?")
    UI->>Backend: POST /api/agent/query { query }
    Note over Backend: Warm-up checks & Actuator status
    Backend->>Gemini: Delegate natural language query
    Note over Gemini: Tool use & Schema matching
    Gemini->>ClickHouse: Execute compiled sub-second SQL
    ClickHouse-->>Gemini: Return columnar rows (Gross, Sentiment)
    Gemini->>Gemini: Formulate response with recommendation & confidence
    Gemini-->>Backend: Return JSON (answer, rec, confidence, risk_factors, query_log)
    Backend-->>UI: Deliver structured payload
    Note over UI: Preprocess text: highlight numbers, bold film titles
    UI-->>Executive: Render markdown answer, Recharts trend line, risk badges

Loading

3. Component & Page Routing Hierarchy

The layout is structured around a responsive sidebar wrapper with modal backdrop overlay support for smaller screens.

graph TD
    App["App.jsx (Router)"] --> WarmUp["WarmUpOverlay.jsx"]
    App --> Sidebar["Sidebar.jsx (Navigation)"]
    App --> Cinematic["CinematicEffects.jsx & Header"]
    
    App --> Dashboard["Dashboard.jsx (/)"]
    App --> AgentQuery["AgentQuery.jsx (/query)"]
    App --> StudioBriefing["StudioBriefing.jsx (/briefing)"]
    App --> AnalyticsCharts["AnalyticsCharts.jsx (/analytics)"]

    Dashboard --> FeaturedGrid["Featured Film Grid (Poster Cards)"]
    Dashboard --> StatRow["Quick Telemetry Row"]
    Dashboard --> Ticker["Cinema Marquee Ticker"]

    AgentQuery --> ChatHistory["Chat History Panel"]
    AgentQuery --> Chips["Quick Prompt Chips"]
    AgentQuery --> Suggested["Suggested Queries Grid"]

    ChatHistory --> MessageBubble["MessageBubble.jsx"]
    MessageBubble --> AgentResponse["AgentResponse.jsx"]

    StudioBriefing --> BriefingFrame["Widescreen Letterbox Frame (2.39:1)"]
    BriefingFrame --> AgentResponse

    AgentResponse --> Markdown["ReactMarkdown (Custom Highlight Renderers)"]
    AgentResponse --> SQLToggle["SQL Query Trace Panel"]
    AgentResponse --> PDFDownload["PDF Exporter & Clipboard Copy"]

    AnalyticsCharts --> Selector["Film Selector Bar"]
    AnalyticsCharts --> AreaCh["Recharts Area Chart (Box Office)"]
    AnalyticsCharts --> LineCh["Recharts Line Chart (Social Sentiment)"]
    AnalyticsCharts --> BarCh["Recharts Dual-Axis Bar Chart (Streaming)"]

Loading

---

📺 Detailed Screen Walkthroughs

1. Executive Dashboard (/)

• Cinematic Movie Marquee Ticker: An endless horizontal scrolling ticker tracking film box office receipts and dynamic status badges (EXTEND, HOLD, PULL).
• Quick Stats Telemetry Row: High-level telemetry diagnostics displaying Active Film Catalog size, database performance metrics (<15ms query execution times), AI Orchestration details, and Remote API Health checks.
• Featured Catalog Performance: Real-time posters displaying the current box office gross and sentiment levels mapped directly from live ClickHouse metrics with responsive hover effects.

2. Conversational Decision Engine (/query)

• Intelligent Chat History: Message log starting with a helpful agent introduction explaining its database access parameters.
• Suggested Queries: Preset prompt buttons offering instant metrics comparison, sentiment tracks, or release leg analysis.
• Quick Chips: Rapid navigation chips to load query examples instantly.
• Dynamic Content Preprocessing: Client-side regex formatters automatically parse returning markdown:
  • Dollar amounts and currency sequences are formatted as inline highlighted telemetry tags (e.g. `$142.4M`).
  • Percentages and risk indexes are wrapped in code blocks for premium visualization (e.g. `-43%`).
  • Recognized film catalog titles are dynamically bolded for executive scannability.

3. Executive Morning Briefing (/briefing)

• Widescreen Scope Presentation: Locked within a cinematic 2.39:1 widescreen frame with matching letterboxing overlays.
• Pre-compiled / Live Compilation: Fetches daily briefings cached from the API. If no cache is found, triggers the CineMetrics AI Agent to run a full database analysis and compile the report on the fly.
• Briefing Operations Panel: Features buttons to download the report as a PDF briefing document or copy the text cleanly to the system clipboard.

4. Real-Time Analytics Visualizer (/analytics)

• Telemetry Origin Badge: Displays ⚡ ClickHouse Live Data when connecting to remote databases, and falls back to a simulated schema feeder if offline.
• Interactive Selector Bar: Allows users to filter the active film registry to populate all charts instantly.
• Recharts Panels:
  • Box Office Revenue: A smooth area chart tracking the weekly gross trajectory with custom gradient fills.
  • Social Sentiment Index: A daily time-series line chart tracking user approval percentages.
  • Streaming Engagement: A dual-axis chart visualizing streaming views (left axis) against video completion rates (right axis).

---

💻 Getting Started

Prerequisites

Make sure you have Node.js (version 18+ recommended) installed.

Installation

Clone the repository and install the project dependencies:

cd cinemetrics-ui
npm install

Running Locally

To launch the hot-reloaded development server:

npm run dev

Open http://localhost:5173 (or the port specified in your console) to view the application.

Production Build

To compile the production assets into static distributions:

npm run build

---

🌐 Remote API Specifications & CORS

The frontend integrates directly with a Google Cloud Run hosted REST endpoint.

Endpoint Details

• Health Actuator Check: GET /actuator/health
  • Checks server connection and database availability.
• AI Agent Query Processing: POST /api/agent/query
  • Body: { query: "string" }
  • Returns: { answer: string, recommendation: string, confidence: number, risk_factors: string[], queries_executed: string[], processing_ms: number }
• Studio Morning Briefing: GET /api/analytics/briefing
  • Returns the pre-compiled morning executive summary.
• Film Directory: GET /api/analytics/films
  • Returns: Array<{ film_id: string, title: string, genre: string, release_date: string, budget_usd: number }>
• Visualizer Feed: GET /api/analytics/chart-data/{filmId}
  • Returns nested arrays containing time-series data for daily box office, hourly sentiment trackers, and platform streaming performance.