# medhachoum/cinematic-landing-kit architecture

> Architecture diagram of the GitHub repository medhachoum/cinematic-landing-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/medhachoum/cinematic-landing-kit
- Repository: https://github.com/medhachoum/cinematic-landing-kit

## Overview

1. **What this repository is**
   This is not a production app codebase; it is a **prompted build system / knowledge pack** for generating cinematic landing pages with **Claude Code**. The repo’s job is to supply persistent project memory, a ready-made HTML scaffold, and Higgsfield prompt structure so the generated page is consistent, luxurious, and visually coherent.

2. **Top-level architecture**
   The repo is organized into three layers:
   - **Execution guidance**: `CLAUDE.md`
   - **Domain memory / rules**: `memory/*.md`
   - **Implementation templates**: `templates/*`
   
   That separation is the key architectural boundary: the model reads instructions and rules first, then fills a working skeleton rather than inventing the system from scratch.

3. **`CLAUDE.md` as the entrypoint**
   `CLAUDE.md` is the operational contract for Claude Code. It likely contains the condensed workflow, quality gates, and the order in which the memory files should be consulted. In architecture terms, it is the **bootstrap layer** that tells the agent how to behave for every project using this kit.

4. **`memory/` as persistent design policy**
   The nine memory files are the real “architecture spec” of the kit. They encode:
   - page construction playbook
   - scroll-film canvas strategy
   - seamless section transitions
   - cinematic hero behavior
   - theming and blend-mode constraints
   - Higgsfield generation pipeline
   - modesty / identity rules
   - preview and environment gotchas
   - quality bar and rejection criteria
   
   This folder functions as a **policy and tribal-knowledge layer**, preventing the agent from repeating known mistakes.

5. **Main rendering model: scroll-driven cinematic page**
   The landing page is architected around a **scroll-film experience** rather than conventional static sections. The core idea is:
   - scroll position drives cinematic progression
   - visuals change as a sequence of scenes
   - transitions are designed to feel like continuous film edits, not discrete page jumps
   
   The readme emphasizes a “Apple × Cartier / Hermès” aesthetic, so the architecture prioritizes motion, atmosphere, and typographic restraint over component density.

6. **Asset-generation pipeline via Higgsfield**
   A major subsystem is the **visual asset pipeline**. Higgsfield is used to generate:
   - reference-informed key visuals
   - matching boundary frames between scenes
   - frame sequences for film-like sections
   - transparent cutouts for the hero
   - web-optimized outputs after validation
   
   The pipeline is driven by prompt templates and controlled by the memory rules, which enforce consistency of identity and style across generated assets.

7. **Template-driven page assembly**
   `templates/index.skeleton.html` is the implementation scaffold for the final landing page. The readme describes it as already working, with only placeholders to fill. This suggests the final page is assembled by replacing templated values rather than authoring from scratch.
   
   Architecturally, this makes the HTML skeleton the **composition layer** where generated copy, theming choices, and assets are bound into a complete landing page.

8. **Prompting contract for asset creation**
   `templates/HIGGSFIELD-PROMPTS.template.md` is a structured prompt template for producing assets. Its role is to standardize the input to Higgsfield so the generated outputs share:
   - consistent product identity
   - correct modesty constraints
   - matching scene boundaries
   - stable visual language
   
   This is an important boundary: prompts are treated as versioned templates, not ad hoc text.

9. **Preview and local validation**
   `templates/launch.json` points to a static preview workflow. The repo expects validation in a real browser, not a hidden tab. The architecture therefore includes a **manual visual QA loop**: generate assets, assemble page, open preview, inspect motion and appearance, then refine.

10. **Technology and runtime constraints that affect architecture**
   The repo’s architecture is shaped by several explicit runtime rules:
   - **Canvas-based sequence rendering** instead of controlling video playback directly
   - **Node.js** for static preview serving
   - **Python + OpenCV** for frame extraction
   - awareness that hidden tabs can pause animation
   - avoidance of brittle tooling assumptions like jq/ffmpeg in the pipeline
   
   These constraints matter because they define what kinds of automation are reliable in the workflow.

11. **Visual system boundaries**
   The memory docs enforce strong boundaries around visual identity:
   - the hero is animated and atmospheric, not a static image with fade
   - transparent cutouts are preferred for moving elements because blend modes break under transforms
   - transitions between sections should be boundary-matched, not crossfaded from unrelated stills
   - theme is chosen per product and must remain consistent across all assets
   
   In diagram terms, the visual system is a set of constrained modules rather than freely composable effects.

12. **Overall data flow**
   The end-to-end flow is:
   **product brief + reference image → Claude reads CLAUDE.md and memory → theme/story/structure decisions → Higgsfield prompt generation → visual asset creation and validation → HTML skeleton population → local preview and QA → final polished landing page**
   
   That is the core architecture of the repository: a **repeatable creative production pipeline** with explicit knowledge, controlled generation, and browser-based verification.

Main entry points: [`CLAUDE.md`](https://github.com/medhachoum/cinematic-landing-kit/blob/main/CLAUDE.md) (CLAUDE.md), [`memory/06-higgsfield-pipeline.md`](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/06-higgsfield-pipeline.md) (Higgsfield Pipeline), [`templates/index.skeleton.html`](https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/index.skeleton.html) (HTML Skeleton), [`templates/HIGGSFIELD-PROMPTS.template.md`](https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/HIGGSFIELD-PROMPTS.template.md) (Prompt Template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_claude["CLAUDE.md<br/>entrypoint<br/>[CLAUDE.md]"]
  node_readme["README<br/>overview<br/>[README.md]"]
end

subgraph group_policy["Policy Memory"]
  node_build_playbook["Build Playbook<br/>workflow rules"]
  node_scroll_film["Scroll Film<br/>canvas model"]
  node_transitions["Transitions<br/>scene linking"]
  node_hero["Cinematic Hero<br/>hero system"]
  node_theming["Theming<br/>style policy<br/>[05-theming.md]"]
  node_higgsfield["Higgsfield Pipeline<br/>asset pipeline"]
  node_modesty["Modesty Rules<br/>identity policy"]
  node_env_gotchas["Env Gotchas<br/>runtime notes"]
  node_quality["Quality Bar<br/>acceptance rules<br/>[09-quality-bar.md]"]
end

subgraph group_templates["Templates"]
  node_skeleton["HTML Skeleton<br/>page scaffold"]
  node_prompts["Prompt Template<br/>prompt contract"]
  node_launch["Launch Config<br/>preview config<br/>[launch.json]"]
end

node_brief_flow{{"Brief Flow<br/>production flow"}}
node_qa_loop(("QA Loop<br/>visual validation"))

node_readme -->|"documents"| node_claude
node_claude -->|"loads"| node_build_playbook
node_claude -->|"loads"| node_scroll_film
node_claude -->|"loads"| node_transitions
node_claude -->|"loads"| node_hero
node_claude -->|"loads"| node_theming
node_claude -->|"loads"| node_higgsfield
node_claude -->|"loads"| node_modesty
node_claude -->|"loads"| node_env_gotchas
node_claude -->|"loads"| node_quality
node_build_playbook -->|"orchestrates"| node_brief_flow
node_brief_flow -->|"generates"| node_prompts
node_prompts -->|"drives"| node_higgsfield
node_higgsfield -->|"produces"| node_qa_loop
node_qa_loop -->|"fills"| node_skeleton
node_skeleton -->|"served by"| node_launch
node_scroll_film -->|"shapes"| node_skeleton
node_transitions -->|"constrains"| node_higgsfield
node_hero -->|"constrains"| node_theming
node_modesty -->|"constrains"| node_prompts
node_env_gotchas -->|"warns"| node_qa_loop
node_quality -->|"checks"| node_qa_loop

click node_claude "https://github.com/medhachoum/cinematic-landing-kit/blob/main/CLAUDE.md"
click node_readme "https://github.com/medhachoum/cinematic-landing-kit/blob/main/README.md"
click node_build_playbook "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/01-build-playbook.md"
click node_scroll_film "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/02-scroll-film-canvas.md"
click node_transitions "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/03-seamless-transitions.md"
click node_hero "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/04-cinematic-hero.md"
click node_theming "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/05-theming.md"
click node_higgsfield "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/06-higgsfield-pipeline.md"
click node_modesty "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/07-modesty-and-identity.md"
click node_env_gotchas "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/08-preview-and-env-gotchas.md"
click node_quality "https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/09-quality-bar.md"
click node_skeleton "https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/index.skeleton.html"
click node_prompts "https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/HIGGSFIELD-PROMPTS.template.md"
click node_launch "https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/launch.json"

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_claude,node_readme toneBlue
class node_build_playbook,node_scroll_film,node_transitions,node_hero,node_theming,node_higgsfield,node_modesty,node_env_gotchas,node_quality toneAmber
class node_skeleton,node_prompts,node_launch toneMint
class node_brief_flow,node_qa_loop toneNeutral
```

## Components

### Bootstrap

Operational entrypoint and repo overview

- [CLAUDE.md](https://github.com/medhachoum/cinematic-landing-kit/blob/main/CLAUDE.md): entrypoint · Operational contract for Claude Code: how to read the kit and execute the workflow · `CLAUDE.md`
- [README](https://github.com/medhachoum/cinematic-landing-kit/blob/main/README.md): overview · Top-level explanation of the kit and its intended production flow · `README.md`

### Policy Memory

Persistent rules for cinematic landing generation

- [Build Playbook](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/01-build-playbook.md): workflow rules · Page construction process and generation sequence · `memory/01-build-playbook.md`
- [Scroll Film](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/02-scroll-film-canvas.md): canvas model · Scroll-driven cinematic page architecture and scene progression · `memory/02-scroll-film-canvas.md`
- [Transitions](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/03-seamless-transitions.md): scene linking · Rules for seamless section boundaries and matched visual handoffs · `memory/03-seamless-transitions.md`
- [Cinematic Hero](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/04-cinematic-hero.md): hero system · Behavior and constraints for the animated hero treatment · `memory/04-cinematic-hero.md`
- [Theming](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/05-theming.md): style policy · Theme selection, blend-mode limits, and consistency constraints · `memory/05-theming.md`
- [Higgsfield Pipeline](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/06-higgsfield-pipeline.md): asset pipeline · Prompt-to-asset generation flow for scene visuals and cutouts · `memory/06-higgsfield-pipeline.md`
- [Modesty Rules](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/07-modesty-and-identity.md): identity policy · Product identity and modesty constraints for generated visuals · `memory/07-modesty-and-identity.md`
- [Env Gotchas](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/08-preview-and-env-gotchas.md): runtime notes · Preview and environment caveats that affect validation and motion behavior · `memory/08-preview-and-env-gotchas.md`
- [Quality Bar](https://github.com/medhachoum/cinematic-landing-kit/blob/main/memory/09-quality-bar.md): acceptance rules · Review criteria and rejection conditions for final output · `memory/09-quality-bar.md`

### Templates

Implementation skeletons and prompt contracts

- [HTML Skeleton](https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/index.skeleton.html): page scaffold · Ready-made landing page structure populated from generated content and assets · `templates/index.skeleton.html`
- [Prompt Template](https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/HIGGSFIELD-PROMPTS.template.md): prompt contract · Structured Higgsfield prompt format for generating consistent assets · `templates/HIGGSFIELD-PROMPTS.template.md`
- [Launch Config](https://github.com/medhachoum/cinematic-landing-kit/blob/main/templates/launch.json): preview config · Static preview launch setup for local browser-based validation · `templates/launch.json`

### Other components

- **Brief Flow**: production flow · Product brief and reference image to theme, prompts, assets, HTML, and preview
- **QA Loop**: visual validation · Browser inspection and iterative refinement after asset generation and page assembly

## Connections

- README → CLAUDE.md: documents · The README explains the kit and how the operational entrypoint is used
- CLAUDE.md → Build Playbook: loads · Claude Code consults the build workflow first
- CLAUDE.md → Scroll Film: loads · Bootstrap instructions point to the scroll-film page model
- CLAUDE.md → Transitions: loads · Bootstrap instructions include the handoff rules between scenes
- CLAUDE.md → Cinematic Hero: loads · Hero behavior is part of the core execution contract
- CLAUDE.md → Theming: loads · Theme and style constraints are consulted during generation
- CLAUDE.md → Higgsfield Pipeline: loads · Asset generation pipeline guidance is part of the core flow
- CLAUDE.md → Modesty Rules: loads · Identity and modesty constraints must be applied during generation
- CLAUDE.md → Env Gotchas: loads · Preview and runtime caveats influence how the kit is executed
- CLAUDE.md → Quality Bar: loads · Acceptance criteria govern final output quality
- Build Playbook → Brief Flow: orchestrates · The playbook coordinates the end-to-end production flow
- Brief Flow → Prompt Template: generates · Brief and reference inputs are turned into structured Higgsfield prompts
- Prompt Template → Higgsfield Pipeline: drives · The prompt template feeds the asset generation pipeline
- Higgsfield Pipeline → QA Loop: produces · Generated assets are validated in-browser before final assembly
- QA Loop → HTML Skeleton: fills · Validated copy and assets populate the HTML scaffold
- HTML Skeleton → Launch Config: served by · The page is opened through the local preview launch config
- Scroll Film → HTML Skeleton: shapes · The scroll-film model determines how the HTML page is structured
- Transitions → Higgsfield Pipeline: constrains · Scene boundaries guide how matching assets are generated
- Cinematic Hero → Theming: constrains · Hero treatment must stay within the selected theme
- Modesty Rules → Prompt Template: constrains · Prompt generation must preserve product identity and modesty rules
- Env Gotchas → QA Loop: warns · Runtime caveats affect how preview validation is performed
- Quality Bar → QA Loop: checks · The quality bar defines what the visual review should reject or accept
