# 02 — Project Architecture Map

This file maps the current TheRoad-I1 architecture to the research concepts in CANVAS and related memory-based storyboard papers.

## Current Pipeline Shape

The current project already has a staged analysis/generation pipeline:

- `step_manifest.py` declares active steps, dependencies, schema versions, resume sensitivity, and model/provider choices.
- `version_registry.py` tracks module versions and prompt dependencies.
- `prompt_loader.py` loads prompt packs by latest version/stem, with drift observability and optional strict mode.
- `shot_staging v13` emits structured shot-level cinematography fields.
- `scene_detail v25` consumes RenderPromptCard as the primary contract.
- `scene_reference_service.py` resolves visible entities, reference image maps, previous-shot background refs, state variants, and image-ref rewrites.
- `image_steps.py` contains image and state-variant generation steps.

## Pipeline Diagram

```mermaid
flowchart TD
  PDF[Input / planning doc] --> Extract[Scene + shot extraction]
  Extract --> Entity[Entity extraction / merge / outlook]
  Extract --> Shot[Shot validation + selection]
  Entity --> Refs[Reference images / outlooks / props]
  Shot --> Camera[scene_camera_flow]
  Camera --> Staging[shot_staging v13]
  Staging --> Consistency[scene_consistency]
  Consistency --> RPC[RenderPromptCard]
  Refs --> RPC
  RPC --> Detail[scene_detail v25]
  Detail --> T2I[T2I prompts]
  Refs --> SceneRef[scene_reference_service]
  SceneRef --> ImageGen[scene image generation]
  T2I --> ImageGen
  ImageGen --> Review[validators / review / persistence]
```

## Local Evidence Anchors

| Area | Current evidence |
|---|---|
| `shot_staging` is active, OpenAI-backed, resume-sensitive, schema v5 | `backend/app/core/step_manifest.py:586-600` |
| `scene_detail` depends on shot staging, scene consistency, background prompt, and downstream shot dependency data | `backend/app/core/step_manifest.py:681-725` |
| prompt versions are explicitly tracked | `backend/app/core/version_registry.py:33-40`, `backend/app/core/version_registry.py:121-127` |
| prompt loader can drift by stem unless packs are copied together | `backend/app/modules/prompt_loader.py:7-24` |
| `shot_staging v13` separates `gaze_direction_kind`, `gaze_target_id`, and `subject_state` | `prompts/_base/shot_staging/13.202605170422/schema.json:30-45` |
| `scene_detail v25` declares RenderPromptCard as primary contract | `prompts/_base/scene_detail/25.202605161320/system.md:3-17` |
| RenderPromptCard is a deterministic card builder with five semantic fields plus render contracts | `backend/app/core/steps/render_prompt_card.py:56-76`, `backend/app/core/steps/render_prompt_card.py:3409-3527` |
| reference service builds image index and rewrites IDs to image refs | `backend/app/services/scene_reference_service.py:34-130` |
| previous-shot background refs enforce source provenance and ref_usage rules | `backend/app/services/scene_reference_service.py:692-952` |
| state variants still have legacy gaze coupling in current code paths | `backend/app/core/steps/image_steps.py:638-669`, `backend/app/services/scene_reference_service.py:954-999`, `backend/app/modules/semantic_contract_router.py:21-107` |

## Research-to-Code Mapping

```mermaid
flowchart LR
  subgraph CANVAS[CANVAS concepts]
    GP[Global continuity plan]
    VM[Visual state memory]
    AR[Anchor retrieval]
    QA[Candidate QA selector]
    MU[Memory update]
  end

  subgraph Road[TheRoad-I1 existing]
    SCF[scene_camera_flow]
    SS[shot_staging]
    RPC[RenderPromptCard]
    SRS[scene_reference_service]
    SD[scene_detail]
    VAL[verify_completion / validators]
  end

  GP --> SCF
  GP --> SS
  VM --> SRS
  AR --> SRS
  AR --> RPC
  QA --> VAL
  MU -. missing explicit layer .-> SRS
```

## Existing Strengths

### 1. Deterministic shot contract

RenderPromptCard already centralizes many prompt rules into structured data. It includes:

- `render_strategy`
- `id_policy`
- `background_binding`
- `continuity_elements_used`
- `asset_requirements`
- `render_contracts`

This is close to CANVAS's shot-level plan, but lower-level. It describes a shot, not the evolving story world.

### 2. Strong version and checkpoint discipline

The manifest and version registry make prompt/schema changes explicit. This is essential if a future memory bank introduces durable state. Every memory shape should follow the same pattern: schema version, config hash, prompt dependency, and fail-fast migration policy.

### 3. Reference image service already exists

`scene_reference_service.py` already knows how to:

- map visible entities to references,
- build labeled image refs,
- rewrite short IDs into image references,
- attach previous-shot background refs,
- enforce source provenance for zoom/background reuse,
- find state variant refs.

That service is the natural home for the first memory retrieval integration, but not necessarily for all memory storage.

### 4. Prompt cleanup direction is correct

Area #1 and Area #2 have moved semantics from regex/prose into structured fields. This aligns with the papers: the system should reason with explicit state, not infer semantics from local strings.

## Main Structural Weaknesses

### 1. No first-class story memory bank

The project has reference images, previous-shot refs, entity metadata, and scene detail checkpoints, but no one durable abstraction equivalent to:

- character appearance state over time,
- location/background anchor state,
- prop state transitions,
- recent frame visual summary,
- generated-image observed facts.

### 2. Post-generation memory update is weak

Many contracts are built before generation. CANVAS updates memory after frame generation. TheRoad-I1 should persist what the generated image actually contains, not only what the prompt asked for.

### 3. Evaluation is mostly contract and residue oriented

The existing gates are strong for prompt contamination, schema drift, and no-silent-fallback. They do not yet answer whether generated images preserve:

- background geometry across reappearing locations,
- prop state after story events,
- character appearance across long gaps,
- shot-to-shot spatial continuity.

### 4. Semantic responsibilities are still split unevenly

The current Area #2 W1/W2 work is a good sign, but legacy consumers still read `gaze_target` in several places until later waves land. The same pattern may exist in other dimensions: state, pose, visibility, background, and prop persistence.

## Recommended Architectural Framing

The project should move toward a three-tier contract stack:

```mermaid
flowchart TD
  Story[StoryWorldMemory<br/>long-range, persistent]
  Scene[SceneContinuityPlan<br/>scene-level, medium-range]
  Shot[RenderPromptCard<br/>shot-level, immediate]
  Prompt[Prompt pack<br/>LLM/VLM execution]
  Image[Generated image]
  Eval[Continuity evaluator]

  Story --> Scene
  Scene --> Shot
  Shot --> Prompt
  Prompt --> Image
  Image --> Eval
  Eval --> Story
```

Interpretation:

- **StoryWorldMemory**: durable and versioned; stores what must persist across scenes.
- **SceneContinuityPlan**: clusters shots by location, character appearance state, prop state, and camera-flow intent.
- **RenderPromptCard**: remains the deterministic shot contract; it should not become a global memory database.
- **Continuity evaluator**: converts generated images into verified observations and memory updates.