System Architecture

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

CineCore Integration

Licensing API

IP Fee Routing

Watch Options

Revenue Reporting

REST API (CineCore v1)

AI Services

ACRCloud (Audio Fingerprinting)

AWS Rekognition (CV)

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

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)

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

Audio Fingerprinting

Full audio track submitted to ACRCloud. Returns song identifications with timestamps. Stored as Song Tag candidates.

ACRCloud API

3

Visual Recognition

Frames submitted to AWS Rekognition for label detection. Results filtered for product-relevant labels (clothing, vehicles, electronics). Stored as Product Tag candidates.

AWS Rekognition

4

Tag Scoring

Confidence scores assigned. High-confidence tags (>85%) auto-published to the Scene Graph. Low-confidence tags (50–85%) enter the human review queue.

Internal scoring service

5

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 catalogue

Step 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 record

Step 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

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, 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