# Boludo (Patrañas) - Argentine Spanish Flashcards App Specification

A native iOS app designed to master authentic Argentine Spanish (*Rioplatense*) verb conjugation, *ser* vs. *estar* distinctions, and Lunfardo/everyday slang expressions through Spaced Repetition (SRS), diverse interactive exercises, native speech synthesis/recognition, and LLM-powered content generation and auditing via Google Gemini.

---

## 1. Design Philosophy & Focus

- **Pure Utility & Argentine Authenticity**: Focused, friction-free tool for acquiring natural Argentine Spanish (*voseo*, Lunfardo slang, authentic grammar, and everyday conversational tone).
- **Anti-Gamification & Calm Flow**: No forced arbitrary daily goals, no hearts or energy limits, no mascot popups, and no guilt-trip notifications.
- **Immediate Mistake Correction**: When a mistake occurs, the app seamlessly provides inline sentence context with highlighted targets for immediate active correction before continuing.
- **Continuous Learning Loop**: Practice flows seamlessly across SRS reviews, distributed exploration, focused mistake drilling, vocabulary matching, and specialized categories.

---

## 2. Core Overview & Target Platform

- **Platform**: Native iOS (SwiftUI, Swift 6, iOS 26+ target).
- **Persistence**: SwiftData for local relational database management with schema migration and offline autonomy.
- **Audio & Speech**:
  - `AVFoundation` (`AVSpeechSynthesizer`) with configurable speech speed and playback modes (*Off*, *Verb Only*, *Whole Sentence*).
  - `Speech` framework (`SFSpeechRecognizer`) for real-time speech input in Audio Translate exercises.
- **Dialect & Grammar**: Argentine Spanish / *Rioplatense*:
  - **Pronouns**: *yo*, *vos* (voseo conjugation: *hablás*, *tenés*, *vivís*, *sos*, *estás*, *sabé*), *él/ella* (descriptive tenses) / *usted* (imperative commands), *nosotros*, *ellos/ellas* / *ustedes*.
  - **Imperative Register Separation**: Full register separation between informal (*vos*: *hablá*, *no hables*) and formal (*usted*: *hable*, *no hable* / *ustedes*: *hablen*, *no hablen*).
  - **Tone & Slang**: Authentic conversational Argentine idioms, lunfardo, and colloquial language (*boludo*, *che*, *posta*, *al pedo*, *mandar fruta*, *bancar*, *laburar*, etc.).
- **AI / LLM Engine**: Google Gemini API with Structured JSON Outputs for fetching lessons, generating Argentine expressions, repairing missing tenses/examples, linguistic auditing, and linking synonyms.

---

## 3. Data Model Architecture (SwiftData)

The database schema models verbs and expressions hierarchically with explicit per-person exercises and SRS tracking:

```
Verb
 ├── Synonyms: [String]
 ├── Tense (present, preterite, imperfect, future, conditional, presentSubjunctive, imperfectSubjunctive, imperative)
 │    └── Persons (yo, tu [vos], el_ella_usted [él / usted], nosotros, ellos_ellas_ustedes [ellos / ustedes])
 │         ├── Proficiency (SRS State: SM-2 parameters)
 │         └── Exercises: [ExerciseItem] (Explicit per-person bespoke sentences)

Expression
 ├── spanishPhrase: String (e.g. "hacerse el gil", "mandar fruta", "al pedo")
 ├── englishMeaning: String
 ├── literalMeaning: String
 ├── category: String (Lunfardo, Everyday Slang, Idiom, Gutter Slang)
 ├── englishExample: String (e.g. "Don't *play dumb*, you know what happened.")
 ├── spanishExample: String (e.g. "No te *hagas el gil*, sabés muy bien lo que pasó.")
 ├── distractors: [String] (3+ contextual conjugated distractors)
 ├── lessonNumber: Int
 └── Proficiency (SRS State: SM-2 parameters)

VerbAuditResult
 ├── id: UUID
 ├── isFlagged: Bool
 ├── issueReason: String?
 ├── suggestedEnglishTemplate: String?
 └── suggestedSpanishTemplate: String?
```

### 3.1 Explicit Per-Person Sentence Architecture
- **Purely Explicit Sentences**: Each `Person` entity owns bespoke `ExerciseItem` records crafted specifically for that grammatical person and tense, eliminating grammatical person and pronoun mismatches.
- **Zero Template Overhead**: All legacy `{Subject}`, `{subject}`, `{verb}`, and `{s|...|...}` placeholders and resolution engines have been completely retired across the database, seed data, and model runtime. All prompts and sentences evaluate directly in $\mathcal{O}(1)$.

---

## 4. Spaced Repetition (SRS) & Practice Modes

### 4.1 SM-2 Progression Algorithm
- **Proficiency Tracking**: Tracks `easeFactor` (default `2.5`, minimum `1.3`), `intervalDays`, `repetitionCount`, `lapseCount`, `nextReviewDate`, and `state` (`new`, `learning`, `review`, `mastered`).
- **Lapse Handling**: On mistakes, interval resets to 1 day, lapse count increments, and the card enters interactive inline correction.
- **Anti-Repetition Guard**: `SRSEngine` guarantees that consecutive cards do not offer the same person or verb back-to-back (`excludingPersonId`).

### 4.2 Practice Distribution Modes
1. **Standard SRS**: Prioritizes cards due for review (`nextReviewDate <= Date.now()`), introducing new cards as reviews clear.
2. **Distributed Practice**: Broad, balanced distribution across all active verbs, tenses, and categories regardless of due dates.
3. **Focus on Mistakes**: Concentrated drilling of cards with low ease factors, recent mistakes, or high lapse counts.
4. **Ser vs Estar**: Dedicated contrast drills distinguishing *ser* and *estar* across corresponding persons and tenses.
5. **Argentine Expressions**: Dedicated drills for idioms, lunfardo slang, and colloquial phrases.

### 4.3 Active Practice Category Filtering
Users can toggle which categories are active during Standard, Distributed, and Mistake Focus modes:
- **Verbs**: Conjugation practice across enabled tenses.
- **Vocabulary (Infinitives)**: 5/5 matching exercises pairing base Spanish verbs with their English meanings.
- **Ser vs Estar**: Specialized contrast drills.
- **Expressions & Lunfardo**: Authentic Argentine idioms and slang.

---

## 5. Exercise Types & Mechanics

All exercise types can be toggled on/off in Settings (with strict persistence across app restarts):

### 5.1 Swipe (Binary Choice) — `icon: hand.draw`
- **UI**: Flashcard with English prompt sentence and two options (left vs. right).
- **Mechanics**: Fast binary decision. Distractors contrast either person (e.g., *hablo* vs *habla*) or tense (e.g., *hablás* [present] vs *hablaste* [preterite]).
- **Interactions**: Drag/swipe gestures or optional on-screen bottom buttons with haptic feedback.

### 5.2 Type (Spanish Conjugation) — `icon: keyboard`
- **UI**: Contextual English prompt with an inline input field for typing the single Spanish conjugated form.
- **Mechanics**:
  - Auto-focuses keyboard with Spanish layout.
  - **Accent Accessory Bar**: One-tap access to `[á] [é] [í] [ó] [ú] [ñ]`.
  - **Synonym & Accent Validation**: Validates exact answers, diacritic-free variations, and registered synonym verbs.

### 5.3 Speak (Audio Translate) — `icon: mic`
- **UI**: English prompt with live waveform microphone visualizer.
- **Mechanics**: Real-time Latin American Spanish speech recognition. Accepts the full sentence or target word. Supports one-tap fallback to typing if in noisy environments.

### 5.4 Multi-Option (4 Choices) — `icon: square.grid.2x2`
- **UI**: 2x2 grid of 4 distinct choices.
- **Mechanics**: Mixes distractors across other persons in the same tense and the same person across other tenses.

### 5.5 1 of 6 (with "Ninguna") — `icon: die.face.6`
- **UI**: 2x3 grid featuring 5 conjugated options plus a fixed 6th option: `"Ninguna"` (*Neither/None*).
- **Two-Stage Dynamic Flow**:
  - **Target Present**: Options 1–5 contain the target word and 4 distractors. Selecting the target completes the card.
  - **Target Absent ("Ninguna" Correct)**: Options 1–5 contain 5 plausible distractors. When the user correctly selects `"Ninguna"`, the card smoothly transitions in-place into a **classic 1-of-4 multiple choice for the same sentence and person** without leaking the answer in the interim banner.

### 5.6 Match 5 Pairs — `icon: rectangle.2.swap`
- **UI & Contextual Headers**:
  - Displays above-card badge tracking (e.g. `IR • PRESENT` or `MATCH THE VERBS`).
  - **Conjugation Mode**: Left column displays randomized person pronouns (`yo`, `vos`, `él / ella / usted`, `nosotros`, `ellos / ellas / ustedes`); right column displays randomized conjugated forms (`voy`, `vas`, `va`, `vamos`, `van`).
  - **Vocabulary Mode**: Left column displays English meanings; right column displays Spanish infinitives.
  - **Expressions Mode**: Left column displays English meanings; right column displays Argentine phrases.
- **Scoring & Mistake Evaluation**:
  - Tracks mistakes made during the exercise: `Score = max(0, 5 - mistakes)`.
  - 5 or more mistakes yields `0/5`.
  - Result banner displays score and praise tiers (e.g. `5/5 • Ir (Present)`, `4/5 • Vocabulario`). Perfect completions increment streak and trigger confetti on milestone streaks.

---

## 6. Recall Preferences & Options Reveal Speeds

- **Delay Options Reveal (Think First)**: Allows users to mentally construct the conjugation before options appear.
- **Stepped Speed Slider with Annotations**:
  - `1.0s` (*Fast*)
  - `1.5s`
  - `2.0s` (*Default*)
  - `3.0s`
  - `5.0s`
  - `Tap` (*On Tap / Slowest*): Options remain obscured as `••••` until the user taps the prompt card or any option button to reveal them.

---

## 7. Library & Reference System

- **Segmented Tabs**: Instant switching between **Verbs** and **Expressions**.
- **Verb Library**:
  - Searchable by Spanish infinitive, English translation, lesson tag, or synonyms.
  - Category filters (`All`, `Base`, `Lessons`, `-ar`, `-er`, `-ir`, `Irregular`).
  - Mastery progress indicators (`Mastered`, `Learning`, `Unstudied`).
  - **Verb Detail View**: Full conjugation matrix across all 8 tenses with color-coded mastery cells, audio pronunciation, and dedicated person example sheets.
  - Context menu & swipe actions: Add AI example to all tenses, audit verb, delete verb.
- **Expression Library**:
  - Searchable by phrase, meaning, or category.
  - Dynamic category pills auto-derived from database (*Lunfardo*, *Everyday Slang*, *Idiom*, *Gutter Slang*).
  - Shows phrase, English meaning, literal translation, and natural example preview.
  - Mastery badge indicators and swipe-to-delete.
- **AI Content Fetching, Auditing & Repair Tools**:
  - **Fetch Lesson**: Generates a new 5-verb lesson pack with full tenses, conjugated forms, and contextual sentences.
  - **Fetch More (Expressions)**: Generates 5 new authentic Argentine expressions, deduplicating against existing phrases.
  - **Sentence Audit Tool (Verb Detail & Library)**:
    - Analyzes generated sentences tense-by-tense with live progress tracking and animated progress bars.
    - Specific prompt rule to detect and flag person/subject mismatches.
    - Bulk action buttons: **Accept All Replacements** (one-tap batch AI replacement) and **Remove Broken** (deletes all flagged sentences).
  - **Library Repair & Audit Modal**:
    - Dedicated screen for repairing and auditing the entire library one-by-one with live metrics (*Audited*, *Flagged*, *Fixed*, *Synonyms*, *Tenses*).
    - Auto-fix toggle to automatically commit AI suggested corrections to database.
    - Non-blocking, cancelable background execution via `Stop & Close` button and `.onDisappear`.
    - **High-Throughput Audit Log**: Batched state updates with windowed `LazyVStack` rendering to handle thousands of log entries smoothly.
  - **In-Practice Exercise Review**: Flag button (`icon: flag`) in the top navigation bar allows users to review any current exercise with Gemini AI and apply fixes on the spot.

---

## 8. Data Management & Settings

- **JSON Export & Restore**: Single-file JSON export and import covering the entire library, custom generated lessons, expressions, and SRS proficiency history.
- **Local Data Reset**: Option to restore bundled base starter verbs and reset progress.
- **Keychain Security**: Gemini API key stored securely in the iOS Keychain.
- **Asynchronous Model Discovery**: Gemini model selector lazily loads defaults with non-blocking manual refresh.
- **Persistent Preferences**: Strict persistence of enabled tenses, exercise types, active practice categories, and delayed reveal timers across app kills and restarts.