docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,714 @@
|
||||
# Storyboard Integration Guide
|
||||
|
||||
**Using Visual Storyboards to Document Complex Component Functionality**
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Complex interactive components (calendars, booking systems, multi-step workflows) have **state transitions** and **interaction flows** that are difficult to describe in text alone.
|
||||
|
||||
**Storyboards** provide visual, sequential documentation of:
|
||||
|
||||
- State transitions (e.g., Empty → Booked → Active → Completed)
|
||||
- User interactions and system responses
|
||||
- Time-based changes (countdowns, timers)
|
||||
- Multi-step workflows
|
||||
|
||||
---
|
||||
|
||||
## Storyboard Types
|
||||
|
||||
### 1. **State Transition Storyboards**
|
||||
|
||||
**Purpose:** Show how a component changes states over time
|
||||
|
||||
**Example:** Dog Week Walk Booking States
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ State Transition Storyboard │
|
||||
│ Component: Walk Time Slot Card │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. WHITE (Empty) → User books │
|
||||
│ [Dog icon] 8-11 → [Book button] │
|
||||
│ │
|
||||
│ 2. GRAY (Booked) → Time arrives │
|
||||
│ [Dog+User] 8-11 │
|
||||
│ │
|
||||
│ 3. ORANGE (Countdown) → User starts │
|
||||
│ [Dog icon] 32 min left → [Start button] │
|
||||
│ │
|
||||
│ 4. BLUE (In Progress) → User completes │
|
||||
│ [Dog+User] Started 09:32 • 23 min ago │
|
||||
│ │
|
||||
│ 5. GREEN (Completed) → Final state │
|
||||
│ [Dog+User] 32 min walk ✓ │
|
||||
│ │
|
||||
│ Alt: RED (Missed) → Window expired │
|
||||
│ [Dog icon] No walk registered ⊖ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**File:** `Sketches/App-Main-Booking-States.jpg` (Dog Week example)
|
||||
|
||||
### 2. **Interaction Flow Storyboards**
|
||||
|
||||
**Purpose:** Show step-by-step user interactions
|
||||
|
||||
**Example:** Calendar Booking Flow
|
||||
|
||||
```
|
||||
Frame 1: User views calendar
|
||||
Frame 2: User taps "Book" button
|
||||
Frame 3: Card transitions to GRAY state
|
||||
Frame 4: Leaderboard updates (+1 point)
|
||||
Frame 5: Week overview quarter circle turns gray
|
||||
```
|
||||
|
||||
### 3. **Multi-Component Storyboards**
|
||||
|
||||
**Purpose:** Show how multiple components interact
|
||||
|
||||
**Example:** Week View + Leaderboard + Calendar Sync
|
||||
|
||||
```
|
||||
Frame 1: User clicks day circle in week overview
|
||||
Frame 2: Calendar scrolls to that day
|
||||
Frame 3: User books walk
|
||||
Frame 4: Week overview quarter circle updates
|
||||
Frame 5: Leaderboard count increments
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Modular Structure
|
||||
|
||||
### Where Storyboards Belong
|
||||
|
||||
| File Type | Contains Storyboard? | Purpose |
|
||||
| --------------- | --------------------- | ------------------------------------- |
|
||||
| **Pages/** | ❌ No | Page layout only |
|
||||
| **Components/** | ⚠️ Visual states only | Static appearance of each state |
|
||||
| **Features/** | ✅ YES | State transitions & interaction flows |
|
||||
|
||||
### Storyboard Storage
|
||||
|
||||
```
|
||||
project-root/
|
||||
├─ Pages/
|
||||
│ └─ 02-calendar-page.md
|
||||
│
|
||||
├─ Components/
|
||||
│ └─ walk-slot-card.component.md
|
||||
│
|
||||
├─ Features/
|
||||
│ ├─ walk-booking-logic.feature.md
|
||||
│ └─ Storyboards/ ← NEW FOLDER
|
||||
│ ├─ walk-state-transitions.jpg
|
||||
│ ├─ booking-flow.jpg
|
||||
│ └─ calendar-sync-flow.jpg
|
||||
│
|
||||
└─ Sketches/ ← Existing page sketches
|
||||
└─ 02-calendar-page-sketch.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature File with Storyboard Reference
|
||||
|
||||
### Example: `walk-booking-logic.feature.md`
|
||||
|
||||
```markdown
|
||||
# Walk Booking Logic Feature
|
||||
|
||||
**Feature ID:** `walk-booking-logic`
|
||||
**Type:** State Machine with Time-Based Transitions
|
||||
**Complexity:** High
|
||||
|
||||
## Purpose
|
||||
|
||||
Manages walk slot state transitions, user booking interactions, and automatic time-based state changes for the Dog Week calendar.
|
||||
|
||||
---
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
**State Transition Flow:**
|
||||
|
||||
|
||||
|
||||
**Key:** This storyboard shows all 6 walk states and the triggers that cause transitions between them.
|
||||
|
||||
---
|
||||
|
||||
## State Definitions
|
||||
|
||||
### State 1: WHITE (Empty / Available)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 1
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- White background
|
||||
- Dog avatar only (no user avatar)
|
||||
- Time range: "8-11"
|
||||
- Action button: "Book" / "Boka"
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Initial state for all unbooked slots
|
||||
- Appears when walk is unbooked
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- User clicks "Book" → GRAY (Booked)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Any family member can book
|
||||
- Booking awards +1 leaderboard point
|
||||
- Updates week overview quarter circle to gray
|
||||
|
||||
---
|
||||
|
||||
### State 2: GRAY (Booked / Scheduled)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 2
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Gray background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Names: "Rufus & Patrick"
|
||||
- Time range: "8-11"
|
||||
- No action button (tap card for details)
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- User books empty slot (WHITE → GRAY)
|
||||
- Walk is scheduled but time window not yet open
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- Time window opens (8:00 arrives) → ORANGE (Countdown)
|
||||
- User unbooks walk → WHITE (Empty)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Shows who booked the walk
|
||||
- Tap card to view details/unbook
|
||||
- Leaderboard point already awarded
|
||||
|
||||
---
|
||||
|
||||
### State 3: ORANGE (Window Open / Countdown)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 3
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Orange background
|
||||
- Dog avatar only (user avatar removed)
|
||||
- Countdown timer: "32 min left" / "32 min kvar"
|
||||
- Warning icon: ⚠️
|
||||
- Action button: "Start" / "Starta"
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Scheduled time arrives (8:00) → GRAY to ORANGE
|
||||
- Real-time countdown updates every minute
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- User clicks "Start" → BLUE (In Progress)
|
||||
- Countdown reaches 0 (11:00) → RED (Missed)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Countdown shows time remaining in window
|
||||
- Urgency indicator (warning icon)
|
||||
- Can only start if no other walk active for this dog
|
||||
|
||||
---
|
||||
|
||||
### State 4: BLUE (In Progress / Active Walk)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 4
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Blue background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Status: "Started 09:32 • 23 min ago"
|
||||
- Refresh icon: ↻
|
||||
- No action button (tap card for completion)
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- User starts walk (ORANGE → BLUE)
|
||||
- Real-time duration updates every minute
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- User completes walk → GREEN (Completed)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Blocks other walks for this dog
|
||||
- Shows elapsed time since start
|
||||
- Tap card to complete walk or view progress
|
||||
|
||||
---
|
||||
|
||||
### State 5: GREEN (Completed)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 5
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Green background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Duration: "32 min walk" / "32 min promenad"
|
||||
- Checkmark icon: ✓
|
||||
- No action button
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- User completes active walk (BLUE → GREEN)
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- None (final successful state)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Permanent record of completed walk
|
||||
- Shows actual walk duration
|
||||
- Unblocks dog for next walk
|
||||
|
||||
---
|
||||
|
||||
### State 6: RED (Missed / Overdue)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 6
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Red background
|
||||
- Dog avatar only (no user avatar)
|
||||
- Message: "No walk registered" / "Ingen promenad registrerad"
|
||||
- Minus icon: ⊖
|
||||
- No action button
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Countdown expires without walk being started (ORANGE → RED)
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- None (permanent accountability record)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Cannot be changed or deleted
|
||||
- Leaderboard point remains (no penalty)
|
||||
- Shows who booked but didn't complete
|
||||
|
||||
---
|
||||
|
||||
## Interaction Flows
|
||||
|
||||
### Flow 1: Successful Walk Booking & Completion
|
||||
|
||||
**Storyboard:** `Storyboards/booking-flow.jpg`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **User views empty slot** (WHITE state)
|
||||
- Sees "Book" button
|
||||
2. **User taps "Book"**
|
||||
- System validates user is family member
|
||||
- System creates booking record
|
||||
3. **Immediate updates:**
|
||||
- Card → GRAY state
|
||||
- Leaderboard: User +1 point
|
||||
- Week overview: Quarter circle → gray
|
||||
4. **Time window opens** (8:00 arrives)
|
||||
- Card → ORANGE state
|
||||
- Countdown timer starts
|
||||
5. **User taps "Start"**
|
||||
- System validates no other active walk for dog
|
||||
- System records start time
|
||||
6. **Immediate updates:**
|
||||
- Card → BLUE state
|
||||
- Duration counter starts
|
||||
- Other walks for dog → disabled
|
||||
7. **User completes walk** (via Walk Details page)
|
||||
- System records completion time
|
||||
- System calculates duration
|
||||
8. **Immediate updates:**
|
||||
- Card → GREEN state
|
||||
- Week overview: Quarter circle → green
|
||||
- Other walks for dog → re-enabled
|
||||
|
||||
---
|
||||
|
||||
### Flow 2: Missed Walk
|
||||
|
||||
**Storyboard:** `Storyboards/missed-walk-flow.jpg`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Walk booked (GRAY state)
|
||||
2. Time window opens (ORANGE state)
|
||||
3. Countdown timer runs
|
||||
4. User doesn't start walk
|
||||
5. Countdown reaches 0 (11:00)
|
||||
6. **Automatic transition:** ORANGE → RED
|
||||
7. Permanent missed walk record created
|
||||
|
||||
---
|
||||
|
||||
### Flow 3: Multi-Component Sync
|
||||
|
||||
**Storyboard:** `Storyboards/calendar-sync-flow.jpg`
|
||||
|
||||
**Components Involved:**
|
||||
|
||||
- Week Overview (top section)
|
||||
- Leaderboard (middle section)
|
||||
- Booking Calendar (bottom section)
|
||||
|
||||
**Sync Flow:**
|
||||
|
||||
1. User books walk in calendar
|
||||
2. **Sync 1:** Week overview quarter circle updates
|
||||
3. **Sync 2:** Leaderboard count increments
|
||||
4. User starts walk
|
||||
5. **Sync 3:** Week overview quarter circle changes color
|
||||
6. User completes walk
|
||||
7. **Sync 4:** Week overview quarter circle turns green
|
||||
|
||||
---
|
||||
|
||||
## State Machine Diagram
|
||||
```
|
||||
|
||||
┌─────────────┐
|
||||
│ WHITE │
|
||||
│ (Empty) │
|
||||
└──────┬──────┘
|
||||
│ User books
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ GRAY │
|
||||
│ (Booked) │
|
||||
└──────┬──────┘
|
||||
│ Time arrives
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ ORANGE │◄──── Countdown timer
|
||||
│ (Countdown) │ updates every 1 min
|
||||
└──┬───────┬──┘
|
||||
│ │
|
||||
User starts │ │ Countdown expires
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────┐ ┌─────────┐
|
||||
│ BLUE │ │ RED │
|
||||
│(Active) │ │(Missed) │
|
||||
└────┬────┘ └─────────┘
|
||||
│ │
|
||||
User completes │ │ Permanent
|
||||
│ │ record
|
||||
▼ ▼
|
||||
┌─────────┐ [END]
|
||||
│ GREEN │
|
||||
│(Complete)│
|
||||
└─────────┘
|
||||
│
|
||||
▼
|
||||
[END]
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Storyboard Creation Guidelines
|
||||
|
||||
### When to Create Storyboards
|
||||
|
||||
Create storyboards for:
|
||||
- ✅ Components with 3+ states
|
||||
- ✅ Time-based transitions (countdowns, timers)
|
||||
- ✅ Multi-step user flows
|
||||
- ✅ Complex interactions between multiple components
|
||||
- ✅ State machines with branching paths
|
||||
|
||||
Don't need storyboards for:
|
||||
- ❌ Simple buttons (hover, active states)
|
||||
- ❌ Static content sections
|
||||
- ❌ Single-state components
|
||||
|
||||
### Storyboard Format
|
||||
|
||||
**Hand-drawn sketches** (recommended):
|
||||
- Quick to create
|
||||
- Easy to iterate
|
||||
- Focus on functionality, not polish
|
||||
- Example: Dog Week `App-Main-Booking-States.jpg`
|
||||
|
||||
**Digital wireframes:**
|
||||
- Use Figma, Sketch, or similar
|
||||
- More polished for client presentations
|
||||
- Easier to update
|
||||
|
||||
**Annotated screenshots:**
|
||||
- Use actual prototype screenshots
|
||||
- Add arrows and labels
|
||||
- Good for documenting existing systems
|
||||
|
||||
### Storyboard Numbering
|
||||
|
||||
Number frames sequentially:
|
||||
```
|
||||
|
||||
1. Initial state
|
||||
2. After user action
|
||||
3. System response
|
||||
4. Next state
|
||||
5. Alternative path
|
||||
|
||||
````
|
||||
|
||||
### Storyboard Annotations
|
||||
|
||||
Include:
|
||||
- **State names** (e.g., "ORANGE - Countdown")
|
||||
- **Trigger descriptions** (e.g., "User taps Start")
|
||||
- **Time indicators** (e.g., "After 32 minutes")
|
||||
- **Icons/symbols** for actions (→ for transitions, ⚠️ for warnings)
|
||||
|
||||
---
|
||||
|
||||
## Feature File Template with Storyboard
|
||||
|
||||
```markdown
|
||||
# {Feature Name} Feature
|
||||
|
||||
**Feature ID:** `{feature-id}`
|
||||
**Type:** {State Machine / Workflow / Calculator / etc.}
|
||||
**Complexity:** {Low / Medium / High}
|
||||
|
||||
## Purpose
|
||||
|
||||
{Brief description of what this feature does}
|
||||
|
||||
---
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
**{Storyboard Type}:**
|
||||
|
||||
|
||||
|
||||
**Key:** {Brief explanation of what the storyboard shows}
|
||||
|
||||
---
|
||||
|
||||
## State Definitions
|
||||
|
||||
{If applicable - for state machines}
|
||||
|
||||
### State 1: {State Name}
|
||||
|
||||
**Visual Reference:** Storyboard Frame {number}
|
||||
|
||||
**Appearance:**
|
||||
- {Visual description}
|
||||
|
||||
**Triggers:**
|
||||
- {What causes this state}
|
||||
|
||||
**Transitions:**
|
||||
- {What states this can transition to}
|
||||
|
||||
**Business Rules:**
|
||||
- {Rules governing this state}
|
||||
|
||||
---
|
||||
|
||||
## Interaction Flows
|
||||
|
||||
### Flow 1: {Flow Name}
|
||||
|
||||
**Storyboard:** `Storyboards/{flow-storyboard}.jpg`
|
||||
|
||||
**Steps:**
|
||||
1. {Step description}
|
||||
2. {Step description}
|
||||
3. {Step description}
|
||||
|
||||
---
|
||||
|
||||
## State Machine Diagram
|
||||
|
||||
{ASCII diagram showing state transitions}
|
||||
|
||||
---
|
||||
|
||||
## Data Requirements
|
||||
|
||||
{API endpoints, data models, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
{Business rules, constraints, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
{Error states, recovery flows, etc.}
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Dog Week Example: Complete Structure
|
||||
|
||||
```
|
||||
Features/
|
||||
├─ walk-booking-logic.feature.md
|
||||
│ ├─ References: Storyboards/walk-state-transitions.jpg
|
||||
│ ├─ Contains: 6 state definitions
|
||||
│ └─ Contains: State machine diagram
|
||||
│
|
||||
├─ calendar-sync.feature.md
|
||||
│ ├─ References: Storyboards/calendar-sync-flow.jpg
|
||||
│ └─ Contains: Multi-component interaction flows
|
||||
│
|
||||
└─ Storyboards/
|
||||
├─ walk-state-transitions.jpg ← Main state storyboard
|
||||
├─ booking-flow.jpg ← Successful booking flow
|
||||
├─ missed-walk-flow.jpg ← Missed walk scenario
|
||||
├─ calendar-sync-flow.jpg ← Component sync flow
|
||||
└─ week-navigation-flow.jpg ← Week navigation interactions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Storyboard Integration
|
||||
|
||||
### 1. Visual Clarity
|
||||
|
||||
**Before (Text only):**
|
||||
|
||||
```
|
||||
When the user books a walk, the card changes to gray,
|
||||
the leaderboard updates, and the week overview changes.
|
||||
```
|
||||
|
||||
**After (With storyboard):**
|
||||
|
||||
```
|
||||
See Storyboard Frame 2-3 for visual state transition.
|
||||
```
|
||||
|
||||
### 2. Developer Understanding
|
||||
|
||||
Developers can:
|
||||
|
||||
- See exact visual states
|
||||
- Understand transition triggers
|
||||
- Identify edge cases visually
|
||||
- Reference storyboard during implementation
|
||||
|
||||
### 3. Design Consistency
|
||||
|
||||
Designers can:
|
||||
|
||||
- Ensure all states are visually distinct
|
||||
- Verify state transitions make sense
|
||||
- Spot missing states or transitions
|
||||
- Create Figma components matching storyboard
|
||||
|
||||
### 4. QA Testing
|
||||
|
||||
QA can:
|
||||
|
||||
- Use storyboard as test script
|
||||
- Verify all states are implemented
|
||||
- Test all transition paths
|
||||
- Identify missing functionality
|
||||
|
||||
---
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### Step 1: Sketch Storyboard
|
||||
|
||||
During UX design phase:
|
||||
|
||||
1. Identify complex interactive components
|
||||
2. Sketch state transitions on paper/whiteboard
|
||||
3. Number frames sequentially
|
||||
4. Add annotations for triggers and transitions
|
||||
5. Take photo or scan
|
||||
|
||||
### Step 2: Store Storyboard
|
||||
|
||||
```
|
||||
Features/Storyboards/{component-name}-{type}.jpg
|
||||
```
|
||||
|
||||
### Step 3: Reference in Feature File
|
||||
|
||||
```markdown
|
||||
## Visual Storyboard
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Step 4: Document States
|
||||
|
||||
For each frame in storyboard:
|
||||
|
||||
- Create state definition
|
||||
- Link to storyboard frame number
|
||||
- Describe triggers and transitions
|
||||
|
||||
### Step 5: Create State Machine
|
||||
|
||||
Convert storyboard to ASCII state machine diagram for quick reference
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Storyboards are essential for:**
|
||||
|
||||
- 🎯 Complex state machines (calendars, booking systems)
|
||||
- 🎯 Multi-step workflows (onboarding, checkout)
|
||||
- 🎯 Time-based interactions (countdowns, timers)
|
||||
- 🎯 Multi-component synchronization
|
||||
|
||||
**Store storyboards in:**
|
||||
|
||||
- `Features/Storyboards/` folder
|
||||
- Reference from Feature files
|
||||
- Link to specific frames in state definitions
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- ✅ Visual clarity for developers
|
||||
- ✅ Design consistency
|
||||
- ✅ QA test scripts
|
||||
- ✅ Stakeholder communication
|
||||
- ✅ Documentation that doesn't get stale
|
||||
|
||||
**Result:** Complex component functionality is documented visually and textually, making implementation and testing straightforward.
|
||||
Reference in New Issue
Block a user