# Experiencias v2 Architecture

## Goal

Experiencias v2 is a reusable engine for guided digital products.

The core model must stay generic. Guides, challenges, onboarding, courses, recipe walkthroughs, and inner-mind scenes are all expressed as:

```txt
Experience
  Screen
  FlowCollection
  Flow
  Step
  Block
```

Domain words can appear in labels and templates, but not as core table names.

## Core Vocabulary

### Experience

The complete product or app.

Examples: AuraSerena, FitFlow, Guerrero Digital.

### Screen

A persistent place in the app.

Examples: Dashboard, Recetario, Guías, Mi Semana, Perfil.

A screen is a stable navigation surface. It can open or embed flows.

### FlowCollection

A reusable set of flows.

Examples: Comer sin ruido, Semana liviana, Reset suave 7 días.

Former names: guide_collection, challenge_collection.

### Flow

A sequence or chapter inside a collection, or a standalone sequence launched by a screen.

Examples: Módulo 1 - Entender la hinchazón, Día 1 - Reset suave, Onboarding de bienvenida.

Former names: guide_module, challenge_template, story, day.

### Step

A navigable unit inside a flow. The user experiences it as one screen or panel.

Examples: text screen, choice screen, checklist screen, scale screen, image screen, recipe step.

Former names: slide, guide block used as screen, scene step.

### Block

A composable layout part inside a step.

Examples: heading, body, image, CTA, choice options, checklist items, progress.

A step can have one main block, but the model supports multiple blocks for richer layouts.

### Renderer

The runtime component that paints a step or flow.

Renderers use data + theme + render preset + motion preset.

### Theme

Brand-level visual identity: colors, base typography, radius, surface palette.

### RenderPreset

How a step or block is presented.

Examples: serene_editorial, inner_mind, premium_recipe_card, soft_choice, cinematic_intro.

### MotionPreset

Reusable animation behavior.

Examples: fade_up_soft, blur_enter, typewriter_dream, smoky_in, smoky_out, slide_next.

### StyleKit

A package tying together theme + render presets + motion presets.

## Editor Shape

The studio is canvas-first by context.

### Studio Contract

The editor must not expose every table as a left sidebar tree. It should expose work areas by authoring intent:

```txt
Studio
  App
    Screens
    Navigation
    Home/dashboard composition
  Library
    FlowCollections
    Assets
    Reusable catalog content
  Flow Editor
    One Flow at a time
    Steps as graph nodes
    StepEdges as configurable routes
  Style
    Theme
    RenderPresets
    MotionPresets
    StyleKits
  Users
    Access
    Progress
    Events
```

### Screen

A `Screen` is a persistent app surface. It answers: **where does the user go?**

Examples: Home, Recetario, Guides, Journey, Profile, My Week.

A screen can:

- render a dashboard layout
- show a menu of FlowCollections
- show one selected FlowCollection
- launch a Flow
- embed a runtime widget
- show catalog content

A screen should not own the detailed content of a flow. It references content by IDs and controls placement/navigation.

Recommended screen config:

```json
{
  "layout": "dashboard",
  "purpose": "continue_journey",
  "preset": "wellness_home",
  "background": {
    "type": "gradient",
    "value": "wellness_soft",
    "overlay": "none"
  },
  "nav": { "enabled": true, "label": "Inicio", "icon": "home", "order": 1 },
  "widgets": [
    {
      "id": "w_hero",
      "type": "hero_text",
      "zone": "hero",
      "config": {
        "eyebrow": "Ahora",
        "title": "Hoy puede ser más simple",
        "subtitle": "Elegí qué necesitás y seguí con una experiencia guiada."
      }
    },
    {
      "id": "w_collection",
      "type": "flow_collection_card",
      "zone": "main",
      "config": { "collection_id": "..." }
    }
  ]
}
```

#### ScreenVisualBuilder

Screens are edited visually through reusable zones and widgets.

Allowed zones:

- `hero`
- `main`
- `secondary`
- `floating`

Allowed first MVP widgets:

- `hero_text`: editorial title/subtitle block.
- `flow_collection_card`: launches or presents a FlowCollection.
- `quick_link`: small navigation/action card.
- `progress_summary`: compact progress widget.
- `media_block`: image/video surface.
- `spacer`: visual spacing.

This keeps screens generic: a Home, Guide menu, Recipe menu, or Profile screen is a composition of the same widget contract, not a hardcoded app-specific component.

Responsive behavior lives under `config.responsive`. Default mode is `auto`, where mobile is authored first and tablet/desktop expand automatically. Custom mode can define presets per viewport:

```json
{
  "responsive": {
    "mode": "custom",
    "breakpoints": {
      "320": { "preset": "single_compact" },
      "mobile": { "preset": "single_comfortable" },
      "tablet": { "preset": "two_column" },
      "desktop": { "preset": "wide_two_column" }
    }
  }
}
```

### FlowCollection

A `FlowCollection` is a reusable package of flows. It answers: **how do we offer a set of flows to the user?**

Examples: Comer sin ruido, Semana liviana, Reset suave 7 dias.

A FlowCollection owns:

- title, subtitle, goal, status
- visual card/widget configuration
- ordering and roles of included flows
- progress rules at collection level
- launch behavior

It does not own the internal step graph of a flow.

Recommended FlowCollection config:

```json
{
  "widget": {
    "variant": "featured_card",
    "emoji": "🌿",
    "image_asset_id": "...",
    "cta_label": "Empezar",
    "progress_mode": "flow_count"
  },
  "display": {
    "show_progress": true,
    "show_flow_count": true,
    "show_duration": true
  }
}
```

### Flow

A `Flow` is the actual navigable graph. It answers: **what happens when the user starts?**

A Flow owns:

- name, subtitle, type, status
- graph behavior
- default style kit
- runtime mode
- steps and edges

It should not define where it appears in the app. Screens and FlowCollections reference it.

Recommended Flow config:

```json
{
  "runtime": "step_flow",
  "entry_step_id": "...",
  "completion": { "mode": "last_reachable_step" },
  "progress": { "mode": "visited_steps" }
}
```

### Step

A `Step` is one navigable node inside a Flow. It answers: **what does the user see/do at this moment?**

Step types define their allowed output handles:

- `cover`, `text`, `image`: `next`
- `choice`: one output per option
- `checklist`: `done`
- `cta`: `action`

This can evolve, but output handles must be generated from step data and remain visible in the editor.

### StepEdge

A `StepEdge` is a route between steps. It answers: **where does this output go?**

Edges are explicit. Creating, deleting, moving, or duplicating steps must not silently rebuild the graph.

Recommended edge condition:

```json
{
  "source_handle": "option:0:si",
  "target_handle": "in",
  "label": "Si"
}
```

### App Map

Shows screens and navigation.

### Flow Editor

Canvas editor for one flow at a time. Each node is a Step.

Clicking a step selects it, opens the inspector, and updates the mobile preview to that exact step.

### Step Inspector

Edits selected step: title, type, render preset, motion preset, blocks, capture key, CTA behavior.

### Preview

Right-side mobile preview always follows selection.

It must support whole screen preview, whole flow preview, and exact selected step preview.

### Responsive Runtime

Every screen and flow must render correctly in four preview targets:

- `320`: old/narrow phones, width 320px.
- `mobile`: modern phone, width 375px.
- `tablet`: tablet layout, width 768px.
- `desktop`: desktop layout, width 1200px.

The preview frame must not fake these sizes. The runtime receives the actual viewport width and CSS/layout rules decide the presentation.

Baseline behavior:

- `320` and `mobile`: single-column, bottom navigation, compact cards.
- `tablet`: wider two-column layouts where useful, navigation can move to a compact top/right position.
- `desktop`: broad layout with hero/content columns and less mobile chrome.

Future editor behavior:

```json
{
  "responsive": {
    "mode": "custom",
    "breakpoints": {
      "320": { "preset": "single_compact" },
      "mobile": { "preset": "single_comfortable" },
      "tablet": { "preset": "two_column" },
      "desktop": { "preset": "wide_two_column" }
    }
  }
}
```

Valid preset names:

- `single_compact`
- `single_comfortable`
- `two_column`
- `wide_two_column`
- `fullscreen`
- `centered`

`mode: auto` means the runtime uses the default mobile-first expansion. `mode: custom` means the selected screen or step can override proportions per viewport.

RenderPresets, Screen layouts, and Step renderers should read these rules instead of hardcoding all responsive behavior in component code.

## Persistence

Postgres is the source of truth.

JSON can exist only as seed fixtures, export/import format, or cached snapshots.

## Migration Rule

Old v1 names are only allowed in migration/import code.

The v2 runtime and editor should not expose: guide_collections, guide_modules, challenge_templates, challenge_collections, day_list, story, slides.

## First Build Scope

1. Postgres schema.
2. Seed AuraSerena demo.
3. App Map.
4. Flow Editor canvas.
5. Step inspector.
6. Mobile preview by selected step.