Frontend · Scene Graph · AI Pipeline · Commerce · CineCore
System Architecture
Full platform architecture — React/Next.js frontend, GraphQL gateway, Neo4j Scene Graph, AI pipeline, CineCore integration, and multi-database data layer.
7
Architecture Layers
Neo4j
Scene Graph DB
5
AI Pipeline Stages
4
CineCore Endpoints
01
Architecture Overview
Scenery is built as a modern web platform with a React/Next.js frontend, a GraphQL API layer for flexible scene graph queries, and a set of backend microservices handling the scene graph, AI pipeline, and commerce operations. CineCore is treated as an external infrastructure dependency accessed via REST API.
Client Layer
Next.js 14 Web App
React Native Mobile (Phase 2)
Filmmaker Onboarding Portal
TypeScript
CDN / Edge
Vercel Edge
Cloudflare CDN
Image Optimisation
Page Caching
API Layer
Apollo Server GraphQL Gateway
REST Endpoints
Auth Middleware (JWT)
Node.js
Service Layer
Film Service
Scene Graph Service
AI Pipeline Service
Commerce Service
User Service
Tour Service
Real Estate Service
CineCore Integration
Licensing API
IP Fee Routing
Watch Options
Revenue Reporting
REST API (CineCore v1)
AI Services
Gemini 2.5 Flash (Vision)
ACRCloud (Song Fingerprinting)
ElevenLabs Scribe v2 (Speech)
Claude Sonnet (Context)
FFmpeg (Frame Extraction)
Python Services
Data Layer
PostgreSQL (relational)
Neo4j (Scene Graph)
Elasticsearch (search)
Redis (cache)
AWS S3 (frames/images)
Infrastructure
AWS EKS (Kubernetes)
Docker
GitHub Actions CI/CD
Monitoring
02
Scene Graph — Technical Design
2.1 Why Neo4j
The Scene Graph is inherently a connected data structure: films link to scenes, scenes link to timestamps, timestamps link to elements (products, songs), elements link to brands and stores. A graph database (Neo4j) enables efficient traversal queries such as "find all products in the car chase scene of Drive" or "show all films where this brand appears" without expensive relational joins.
2.2 Graph Schema
| Node Type | Key Properties |
|---|---|
Film | film_id, title, year, synopsis, poster_url, status |
Scene | scene_id, film_id, title, start_ts, end_ts, thumbnail_url |
Timestamp | ts_id, scene_id, position_seconds |
Product | product_id, name, brand_id, category, image_url, price_eur, purchase_url |
Song | song_id, title, artist_id, album, isrc, duration_sec |
Artist | artist_id, name, genre, spotify_id, deezer_id |
Brand | brand_id, name, logo_url, official_site, is_verified |
Store | store_id, name, type (online/local), address, lat, lng |
User | user_id, username, reputation_score, contribution_count |
Tag | tag_id, ts_id, element_id, element_type, source, confidence, status |
Location | location_id, name, type (hotel/restaurant/apartment/venue/filming_location), address, lat, lng, booking_url, sale_url, hire_url, hire_rate_eur, is_filming_location |
RealEstateListing | listing_id, location_id, listing_type (short_term_rental | sale | filming_hire), price_eur, availability_url, commission_rate, partner_ref |
Dish | dish_id, name, description, recipe_url, cuisine_type |
Tour | tour_id, title, operator_id, price_eur, duration_hours, city, film_ids[], location_ids[], booking_url |
TourOperator | operator_id, name, bio, verified, commission_rate, payout_account |
2.3 Key Graph Relationships
(Film)-[:HAS_SCENE]->(Scene)
(Scene)-[:HAS_TIMESTAMP]->(Timestamp)
(Timestamp)-[:HAS_TAG]->(Tag)
(Tag)-[:REFERENCES]->(Product | Song | Brand)
(Product)-[:SOLD_BY]->(Store)
(Product)-[:MADE_BY]->(Brand)
(Song)-[:PERFORMED_BY]->(Artist)
(User)-[:SUBMITTED]->(Tag)
(Tag)-[:REFERENCES]->(Location | Dish)
(Tour)-[:COVERS]->(Location)
(Tour)-[:BASED_ON]->(Film)
(TourOperator)-[:OPERATES]->(Tour)
(Location)-[:HAS_LISTING]->(RealEstateListing)
(Tag)-[:REFERENCES]->(RealEstateListing)
03
AI Tagging Pipeline
The AI pipeline is event-driven. When a new film is registered, an ingestion event is published. The pipeline processes the film asynchronously in five stages:
1
Frame Extraction
Video frames extracted at 1fps and 5fps (action sequences). Stored in S3 for downstream processing.
FFmpeg + AWS S3
2
Song Fingerprinting
Full audio track submitted to ACRCloud. Identifies commercial music tracks with timestamps — song title, artist, label. Stored as Song Tag candidates.
ACRCloud API
3
Speech Transcription
Audio sent to ElevenLabs Scribe v2 for speaker-diarised transcription. Returns word-level timestamps, speaker attribution, and audio event tags ([music], [silence], [laughter]). Stored as Dialogue and AudioEvent nodes.
ElevenLabs Scribe v2
4
Visual Analysis
Keyframes submitted to Gemini 2.5 Flash for multimodal scene analysis. Returns lighting, framing, colour grading, objects, camera movement, and mood as structured JSON. Stored as Scene attribute nodes and Product Tag candidates.
Gemini 2.5 Flash
5
Context Analysis
Gemini vision output and ElevenLabs transcript passed to Claude Sonnet for higher-order cinematic reasoning — director influence, symbolism, narrative function, and thematic tags. Stored as Theme and Context nodes.
Claude Sonnet
6
Tag Scoring
Confidence scores assigned across all tag sources. High-confidence tags (>85%) auto-published to the Scene Graph. Low-confidence tags (50–85%) enter the human review queue.
Internal scoring service
7
Human Review
Shop curators, brands, and admins review flagged tags. Corrections update confidence score and source attribution. Approved tags become live.
Admin / Shop UI
04
Commerce Layer Architecture
4.1 Product Placement Flow
Step 1
Retailer registers via
POST /shops and submits product catalogueStep 2
Retailer navigates to a film timestamp and places a product via the timeline UI
Step 3
System validates product → film link, triggers CineCore IP license check
Step 4
CineCore calculates IP licensing fee (8–12%) and creates a
RevenueSplit recordStep 5
Product tag published at timestamp; affiliate link generated with full tracking context
Step 6
User clicks product → redirected to retailer; click event logged with film/scene/product context
Step 7
On sale confirmation, retailer reports conversion; IP fee processed via CineCore
4.2 Affiliate & Revenue Tracking
- Every outbound product/music/watch link is wrapped in a Scenery affiliate redirect
- Click events logged with
film_id, scene_id, timestamp, element_id, user_id - Conversion events received via retailer webhook or affiliate network callback
- Revenue dashboard aggregates earnings by film, scene, product category, and period
05
Frontend Architecture
5.1 Key Pages & Components
| Route | Page | Key Components |
|---|---|---|
| / | Home / Discovery | Trending films, editorial picks, search bar |
| /film/:id | Film Page | Metadata, cast, watch options, scene timeline, product/music panels |
| /film/:id?t=:timestamp | Film Page (deep link) | Timeline pre-scrolled to timestamp; elements panel pre-loaded |
| /product/:id | Product Page | Product info, brand, purchase options, related scenes |
| /shop/onboard | Shop Onboarding | Retailer registration, product catalogue import, curation tutorial |
| /filmmaker/register | Filmmaker Portal | Film registration, self-tagging, IP licensing activation |
| /admin | Admin Dashboard | Tag moderation queue, analytics, dispute management |
| /tours | Movie Tours | Browse tours by film, city, or price; featured tours, search & filter |
| /tours/:id | Tour Detail | Tour description, itinerary, locations map, price, booking CTA |
| /tour-operator/register | Tour Operator Portal | Operator onboarding, tour creation, location linking, payout setup |
| /locations/:id/rent | Rental Listing | Short-term rental detail, availability, pricing, booking CTA with affiliate tracking |
| /locations/:id/buy | Sale Listing | Property sale referral page, agent contact, Scenery referral ID passed to partner |
| /locations/:id/hire | Filming Location Hire | Location hire for productions, rate card, availability enquiry, commission capture |
5.2 Scene Timeline Component
The timeline is the platform's primary UX innovation. It renders as a horizontal scrubber with scene markers. As the user moves the scrubber position, a GraphQL subscription query updates the active scene's product and music panels in real time. Scenes with high element density are visually highlighted to encourage exploration.
06
CineCore Integration Points
GET
/v1/films/{"{id}"}/license?territory={"{country}"}
Returns streaming/rental/buy options for user territory — powers the "Watch" section on film pages.
POST
/v1/films/{"{id}"}/merchandise-license
Creates IP license record when shop places product at timestamp — triggers revenue split calculation.
POST
/v1/films/{"{id}"}/transaction
Reports merchandise sale for revenue split calculation — routes IP licensing fee to rights holder.
GET
/v1/films/{"{id}"}
Pulls film status and rights holder info for the filmmaker portal and IP licensing activation.
07
Data Layer Design
PostgreSQL
User accounts, shop registrations, tour operator registrations, tour bookings, real estate listings, rental/sale/hire referral tracking, affiliate tracking, revenue records, audit logs
Neo4j
Scene Graph — films, scenes, timestamps, elements, tags, and all relationships
Elasticsearch
Film search index — full-text search across titles, cast, directors, and scene elements
Redis
Session cache, timeline query cache (TTL: 5 min), rate limiting counters
AWS S3
Film frame images for timeline thumbnails, product images, AI processing queue
Infrastructure
Deployment Stack
AWS EKS (Kubernetes)
Docker Containers
GitHub Actions CI/CD
Vercel (Frontend)
Monitoring + Alerting