project-outline

Instruction file imported from HandsomeStrife/vino-recall (.cursor/rules/project-outline.mdc). Copyright stays with the author.

Project Name: VinoRecall Type: Educational Web Application (SaaS) Core Methodology: Spaced Repetition System (SRS) - WaniKani Style Subject Matter: Wine Education

1. Executive Summary

VinoRecall is a visually immersive study platform designed to help wine students pass WSET Level 1 and Level 2 exams. Unlike traditional text-heavy study guides, VinoRecall uses a WaniKani-style Spaced Repetition System (SRS) to present high-quality visual flashcards. The platform uses objective correctness tracking for multiple-choice questions, automatically determining when cards should be reviewed based on answer accuracy.

2. Design Philosophy & UI/UX

The application prioritizes visual learning over text density. The interface should feel like a premium digital wine cellar—warm, inviting, and sophisticated.

Visual Style: Deep Burgundies (#561C24, #9E3B4D), Forest Greens (#2D3F2F), and Cream tones (#FFFBF2, #FFE9CC). High usage of photography (vineyards, bottles, grapes).

Layout (Logged In):

• Horizontal Navigation Header: Fixed burgundy navigation bar at top with logo, menu items, user dropdown
• Hero Section: Full-width background imagery with gradient overlay featuring enrolled deck cards
• Main Canvas: Scrollable, card-based interface with clean white sections on cream background
• Mobile Responsive: Collapsible hamburger menu, touch-optimized interactions

Interaction: Soft transitions, automatic correctness detection, satisfying visual feedback for correct/incorrect answers.

3. Content Scope (The Curriculum)

The app is divided into two distinct "Worlds" (Levels), based on the WSET syllabus.

Level 1: The Foundation

• Grape Identification: Visual cards showing grape clusters -> User identifies the grape (e.g., Merlot, Chardonnay)
• Tasting Technique: The "SAT" (Systematic Approach to Tasting). Identifying acid, tannin, and body
• Food & Wine: Basic pairing principles (e.g., Salt + Acid = Good)
• Service: Glassware types and serving temperatures

Level 2: The Intermediate

• Geography: Map-based cards. Show a highlighted region on a map -> User identifies the region (e.g., Bordeaux, Rioja)
• Label Terminology: Images of wine labels with blurred sections -> User identifies the missing term (e.g., "Grand Cru")
• Production: Diagrams of winemaking (Red vs. White vs. Rosé processes)
• Varietals in Depth: Linking regions to grapes (e.g., Marlborough -> Sauvignon Blanc)

4. Feature Breakdown

A. Learning Materials (Pre-Study Phase)

Before users begin flashcard study, decks can optionally present learning materials to provide context and foundational knowledge.

Features:

• Rich Text Content: Materials use Trix editor supporting formatted text, lists, headings
• Image Integration: Featured images with flexible positioning (top, left, right, bottom)
• Multiple Materials: Each deck can have multiple materials presented in sequence
• Sortable: Admins can drag-and-drop to reorder materials

User Flow - First Study Session:

1. Materials Phase: When first starting a deck, users are presented with all learning materials
2. Navigation: Users can navigate forward/backward through materials, or skip entirely
3. Intermediary Screen: After completing materials (or skipping), an intermediary screen appears
4. Begin Flashcards: User proceeds to the standard flashcard study interface

Re-review Materials:

• Materials are only shown once per user per deck (tracked in deck_user.has_viewed_materials)
• Users can re-review materials anytime via "Review Materials" link on deck stats page
• Re-reviewing materials does not affect SRS scheduling or study progress

Admin Management:

• Accessible via "Materials" link in deck management table
• Create, edit, delete materials with rich text editor
• Upload and position images within materials
• Drag-and-drop reordering of materials

B. The "Study Interface" (Core Feature)

This is the primary screen where the user spends 90% of their time.

Flow:

1. Learning Materials (First Time Only): Optional pre-study content with skip option
2. Intermediary Screen: Transition message before beginning flashcards
3. The Prompt: A card appears with an image or question
4. Answer Selection: For multiple-choice, user selects an answer
5. Instant Feedback: System automatically shows if answer is correct or incorrect
6. Continue Button: User proceeds to next card (Space/Enter hotkey)

SRS Logic - WaniKani Style:

• Correct Answer: Next review exponentially increases (1 day → 2.5 days → 6.25 days, etc.)
• Incorrect Answer: Review in 4 hours
• Ease Factor: Dynamically adjusts (increases +0.1 for correct, decreases -0.2 for incorrect)
• Traditional Cards: Default to correct (for non-multiple-choice content)

C. The Dashboard - Hero Section

A visually rich overview of the user's "Wine Journey" with WaniKani-inspired layout.

Hero Section:

• Full-width vineyard background with gradient overlay
• Welcome message with user name and current streak
• Featured Deck Cards (2-3 decks):
  • Large card with deck image background
  • Due cards count prominently displayed
  • Retention rate percentage (correct answers ratio)
  • Progress bar (reviewed / total cards)
  • "Start Review" button

Content Sections:

• Daily Goal: Circular progress indicator showing cards reviewed today (target: 20 cards), weekly streak dots
• Recent Mistakes: List of incorrectly answered cards with timestamps, link to review mistakes
• Recent Activity: Timeline of recent reviews with correct/incorrect indicators (green checkmark / red X)
• Available Decks: Grid of decks not yet enrolled, with thumbnails and enroll buttons

D. The Library (Deck Browser)

Users can browse and enroll in specific decks.

Features:

• Grid layout with deck thumbnails (uses default images 1.jpg - 10.jpg based on deck ID)
• Deck information: name, description, card count
• Enrollment system with unique shortcodes
• Filter by: Red Wines, White Wines, Regions, Production, Spirits (for L2)

E. User Progression

Metrics Tracked:

• Cards Mastered: Total cards with high retention
• Current Streak: Consecutive days of study
• Retention Rate: Percentage of correct answers per deck
• Daily Reviews: Number of cards reviewed today

Future: Leveling System with badges (e.g., "Sommelier in Training", "Vintner") based on cards mastered.

5. Site Map

1. Public Facing (Logged Out)

• Landing Page: High-impact visuals, value proposition, "The Science of SRS," Pricing, Success Stories
• Auth Pages: Login / Register

2. Application (Logged In)

• Dashboard: Hero with deck cards, daily goal, mistakes, recent activity, available decks
• Study Interface: Three-phase study flow (materials → intermediary → flashcards)
• Material Viewer: Standalone review of learning materials
• Library: Deck browser with enrollment
• Deck Stats: Detailed statistics per deck with materials review link
• Profile/Settings: Subscription management, user preferences

3. Admin Console

• Deck Management: Create, edit, delete decks with card and material management
• Material Management: Rich text editor for creating learning materials with image uploads
• Card Management: Multiple-choice flashcard creation and editing

6. Technical Architecture

SRS Algorithm (WaniKani-Style)

The system uses objective correctness tracking rather than subjective difficulty ratings:

Core Logic:

• Multiple-choice cards: System compares selected answer with correct answer
• Correct → is_correct = true, rating = 'correct'
• Incorrect → is_correct = false, rating = 'incorrect'
• Traditional cards: Default to correct (for self-assessment content)

Review Intervals:

• Incorrect: 4 hours
• Correct (First time): 1 day
• Correct (Subsequent): Previous interval × ease_factor
• Ease Factor: Starts at 2.5, increases +0.1 for correct (max 3.0), decreases -0.2 for incorrect (min 1.3)

Database Schema:

• card_reviews.rating: 'correct' or 'incorrect'
• card_reviews.is_correct: boolean
• card_reviews.selected_answer: stores user's answer for multiple-choice
• card_reviews.ease_factor: dynamic difficulty adjustment
• card_reviews.next_review_at: calculated review time

Learning Materials System

Materials provide contextual learning content before flashcard study begins.

Database Schema:

• deck_materials table:
  • deck_id: Foreign key to deck
  • title: Optional title for the material
  • content: Rich text content (longText)
  • image_path: Optional featured image path
  • image_position: Enum (top, left, right, bottom)
  • sort_order: Integer for ordering materials
• deck_user.has_viewed_materials: Boolean tracking if user has seen materials

Material Repository:

• getByDeckId($deck_id): Get all materials for a deck, ordered by sort_order
• findById($id): Find a specific material
• hasMaterials($deck_id): Check if deck has any materials
• countByDeckId($deck_id): Count materials for a deck

Material Actions:

• CreateMaterialAction: Creates new material with automatic sort_order assignment
• UpdateMaterialAction: Updates existing material content and metadata
• DeleteMaterialAction: Deletes material and re-orders remaining materials
• UpdateMaterialSortOrderAction: Bulk update sort order for drag-and-drop

Frontend Components:

• DeckMaterials (Livewire): Admin interface for CRUD operations on materials
• MaterialViewer (Livewire): User-facing material display with navigation
• Trix Editor (Blade Component): Rich text editor with image upload support

Study Flow Integration:

• StudyInterface tracks phase: 'materials', 'intermediary', or 'flashcards'
• On first study session, phase starts at 'materials' if deck has materials and user hasn't viewed them
• Users can navigate through materials or skip entirely
• After materials, intermediary screen shows "Ready to Begin?" message
• Subsequent sessions skip directly to flashcards phase

Deck Management

• Enrollment System: Each user-deck relationship has a unique 8-character shortcode
• Image System: Decks can have custom images or use default images (1.jpg - 10.jpg based on deck ID modulo 10)
• DeckImageHelper: Centralized helper for consistent image paths

Navigation Architecture

• Header-based Navigation: Replaced sidebar with horizontal burgundy header
• Responsive Design: Mobile hamburger menu, collapsible on small screens
• Study Mode: Navigation hidden during review sessions for focus

Repository Pattern

• CardReviewRepository Methods:
  • getMistakes($user_id, $limit): Recent incorrect answers
  • getRetentionRate($user_id, $deck_id): Percentage of correct answers
  • getDueCardsForUser($user_id): Cards due for review
  • getCurrentStreak($user_id): Consecutive study days
• DeckRepository Methods:
  • getAvailableDecks($user_id): Decks not yet enrolled
  • getUserEnrolledDecks($user_id): User's active decks
  • findByShortcode($user_id, $shortcode): Find deck by unique user shortcode
• MaterialRepository Methods:
  • getByDeckId($deck_id): Get all materials for a deck
  • hasMaterials($deck_id): Check if deck has materials
  • findById($id): Find specific material
  • countByDeckId($deck_id): Count materials for a deck

Frontend Components

• Blade Components: Header, hero sections, stat cards, deck cards, Trix editor
• Livewire User Components: Dashboard, StudyInterface, Library, MaterialViewer, DeckStats
• Livewire Admin Components: DeckManagement, CardManagement, DeckMaterials
• AlpineJS: Dropdown menus, mobile navigation, interactive elements
• TailwindCSS: Utility-first styling with custom burgundy/cream theme
• Trix Editor: Rich text editing with image attachment support (loaded via CDN)
• SortableJS: Drag-and-drop functionality for material reordering

7. Image Optimization

Visual First Approach:

• High-quality photography for decks and cards
• Default image library (10 vineyard/wine images)
• Lazy loading for performance
• Background images with gradient overlays for readability

8. Mobile First

70% of users will study on their commute:

• Touch-optimized card interactions
• Responsive hero section (stacks on mobile)
• Hamburger navigation menu
• Large touch targets for buttons
• Space/Enter keyboard shortcuts for desktop power users

9. Key Differentiators from Anki

VinoRecall uses a WaniKani-style approach rather than Anki:

• Objective vs Subjective: System determines correctness automatically for multiple-choice
• Simplified Ratings: Only correct/incorrect (not again/hard/good/easy)
• Visual First: Hero dashboard with deck imagery
• Retention Focus: Emphasizes accuracy percentage over ease perception
• Shorter Incorrect Intervals: 4 hours (not 1 minute) for realistic re-learning