Add dictionary feature with term management and UI components

- Implement backend API for term CRUD operations - Add frontend dictionary page with search and filtering - Integrate shadcn/ui components (Dialog) - Create term management UI with add/edit/delete functionality - Update database seed with initial terms - Add API client for term operations - Complete Phase 2 of development plan
2026-01-17 18:15:01 +01:00
parent bbf143a3b4
commit c6d6c18466
21 changed files with 1757 additions and 176 deletions
--- a/main-plan.md
+++ b/main-plan.md
@@ -5,6 +5,139 @@ This document provides a complete implementation plan for a 1:1 functional and v

 ---

+## 🎯 CORE APPLICATION FUNCTIONALITY (Quick Reference)
+
+**The application is a Croatian Sign Language learning tool with THREE main interconnected screens:**
+
+### 1️⃣ RIJEČI (Dictionary) - Browse & Add Words
+- **What it shows:** Grid of pre-recorded sign language words with icons
+- **What you do:**
+  - Click **"Dodaj"** (Add) to add words to your sentence
+  - Click **"Info"** to watch the sign video for any word
+- **Screenshot reference:** `1 dodaj rijeci.png`
+
+### 2️⃣ ZNAKOPIS (Sentence Builder) - Order & Save
+- **What it shows:** All words you added, displayed as draggable tokens
+- **What you do:**
+  - Drag and drop words to arrange them in correct sentence order
+  - Create multiple sentences across multiple pages
+  - Click **"Spremi"** (Save) to save document to cloud (stored under your user account)
+- **Screenshot reference:** `2 dodaj rijeci znakopis.png`
+
+### 3️⃣ VIDEO REČENICA (Video Player) - Watch & Learn
+- **What it shows:** Video player + sentence list
+- **What you do:**
+  - Click Play to watch all sign videos play in sequence
+  - Current word being signed is **highlighted** in the sentence list
+  - Control playback (pause, speed, navigate)
+- **Screenshot reference:** `3 dodaj rijeci recenica.png`
+
+### 🔄 Complete User Journey:
+```
+RIJEČI (add words) → ZNAKOPIS (order & save) → VIDEO REČENICA (play & watch)
+                                    ↓
+                            OBLAK (cloud storage)
+                    (documents saved under user account)
+```
+
+**Key Technical Points:**
+- Words are pre-recorded in the database with associated sign videos
+- Sentence state persists across all three screens (global state management)
+- Documents are saved to database and associated with logged-in user
+- Video playback is synchronized with word highlighting
+- All Croatian text labels must match exactly
+
+---
+
+## 📊 DATA FLOW & STATE MANAGEMENT
+
+### How the Three Screens Work Together
+
+**1. Pre-recorded Words (Database)**
+```
+Terms Table:
+- id: uuid
+- wordText: "dobar" (good)
+- wordType: ADJECTIVE
+- cefrLevel: A1
+- iconAssetId: "path/to/icon.png"
+
+TermMedia Table:
+- termId: (links to Term)
+- kind: VIDEO
+- url: "/uploads/videos/dobar.mp4"
+- durationMs: 2500
+```
+
+**2. User Adds Words (Frontend State → Database)**
+```
+User clicks "Dodaj" in Riječi
+    ↓
+Word added to sentenceStore (Zustand)
+    ↓
+User navigates to Znakopis
+    ↓
+sentenceStore displays tokens
+    ↓
+User reorders tokens via drag-and-drop
+    ↓
+User clicks "Spremi" (Save)
+    ↓
+API call: POST /api/documents
+    ↓
+Database creates:
+  - Document (title, ownerUserId)
+  - DocumentPage (documentId, pageIndex)
+  - Sentence (documentPageId, sentenceIndex)
+  - SentenceToken[] (sentenceId, termId, tokenIndex, displayText)
+```
+
+**3. User Plays Video (Database → Frontend)**
+```
+User navigates to Video Rečenica
+    ↓
+Loads document from Oblak or current sentenceStore
+    ↓
+API call: GET /api/playlists/generate?sentenceId=xxx
+    ↓
+Backend resolves:
+  Sentence → SentenceTokens → Terms → TermMedia (videos)
+    ↓
+Returns playlist:
+  [
+    { tokenId, termId, displayText, videoUrl, durationMs },
+    { tokenId, termId, displayText, videoUrl, durationMs },
+    ...
+  ]
+    ↓
+Frontend plays videos sequentially
+    ↓
+Highlights current token in sentence list
+```
+
+### State Management Strategy
+
+**Frontend State (Zustand stores):**
+- `sentenceStore`: Current sentence being built (tokens, order)
+  - Used by: Riječi (add), Znakopis (edit), Video Rečenica (play)
+  - Persists across navigation
+  - Cleared when document is saved or loaded
+
+- `documentStore`: Current loaded document
+  - Used by: Znakopis (edit), Oblak (list), Video Rečenica (play)
+  - Contains: documentId, title, pages[], sentences[]
+
+- `authStore`: Current user session
+  - Used by: All screens
+  - Contains: userId, email, role, isAuthenticated
+
+**Backend Persistence:**
+- All saved documents stored in MySQL via Prisma
+- Documents linked to User via ownerUserId
+- Full hierarchy: Document → DocumentPage → Sentence → SentenceToken → Term
+
+---
+
 ## 1. Technology Stack (PoC-Optimized)

 ### Frontend
@@ -1013,54 +1146,141 @@ VITE_UPLOADS_URL=http://localhost:3000/uploads

 ## 8. Key Features & User Flows

-### 8.1 Dictionary Search Flow
-1. User navigates to "Riječi" (Dictionary)
-2. User enters search term in "Riječ" input
-3. User optionally selects "Tip riječi" (word type) filter
-4. User optionally selects "CEFR razina" (level) filter
-5. User clicks "Traži" (Search)
-6. Grid updates with filtered results
-7. User clicks "Info" on a card
-8. Modal opens showing:
-   - Word details
-   - Sign video (auto-plays)
-   - Examples
-   - Metadata
-9. User can click "Dodaj" to add word to current sentence
+### CORE FUNCTIONALITY OVERVIEW (Based on Screenshots 1, 2, 3)

-### 8.2 Sentence Building Flow
-1. User searches for words in Dictionary
-2. User clicks "Dodaj" on multiple word cards
-3. Words are added to sentence store
-4. User navigates to "Znakopis"
-5. Tokens appear in TokenTray
-6. User drags tokens to reorder
-7. User can remove tokens
-8. User clicks "Spremi" (Save)
-9. Document is saved to cloud (if logged in) or local storage
-10. User can create multiple sentences across pages
+**The application has THREE main interconnected screens that form the primary workflow:**

-### 8.3 Video Playback Flow
-1. User builds or loads a sentence in Znakopis
-2. User navigates to "Video rečenica"
-3. Sentence tokens appear in right panel
-4. User clicks play button
-5. Videos play sequentially for each token
-6. Current token is highlighted
-7. User can pause, skip, or adjust speed
-8. User can navigate between pages/sentences
+#### Screen 1: Riječi (Dictionary) - "1 dodaj rijeci.png"
+**Purpose:** Browse pre-recorded sign language words and add them to your sentence.

-### 8.4 Cloud Document Flow
-1. User logs in
-2. User creates sentences in Znakopis
-3. User saves document to cloud
-4. User navigates to "Oblak"
-5. Document appears in list
-6. User can:
-   - Load document into Znakopis
-   - Delete document
-   - Share document (get link)
-   - View document metadata
+**Key Elements:**
+- Grid of word cards with icons/illustrations
+- Each card has two buttons:
+  - **"Dodaj"** (Add) - Adds the word to the current sentence being built
+  - **"Info"** - Opens a modal/detail view showing the sign video for that word
+- Filter bar at top with search and CEFR level filters
+- Words are color-coded by difficulty level (green/yellow/orange)
+
+**User Actions:**
+1. Browse or search for words
+2. Click "Dodaj" to add words to the sentence (words accumulate at the top of the page)
+3. Click "Info" to watch the sign video demonstration for any word
+4. Continue adding multiple words to build a complete sentence
+
+---
+
+#### Screen 2: Znakopis (Sentence Builder) - "2 dodaj rijeci znakopis.png"
+**Purpose:** Organize the words you've added into a proper sentence order and save as a document.
+
+**Key Elements:**
+- **Top area:** Shows the current sentence with all added words as tokens/chips
+- **Right panel:** "Popis rečenica" (Sentence List) showing:
+  - All sentences in the current document
+  - Page navigation (e.g., "1 / 2 stranica")
+  - Document management controls
+- **Main workspace:** Area to reorder words via drag-and-drop
+- **Action buttons:**
+  - "Spremi" (Save) - Saves the document to cloud storage under your user account
+  - "Učitajte dokument" (Load Document) - Loads a previously saved document
+  - "Nova rečenica" (New Sentence) - Creates a new sentence on a new page
+
+**User Actions:**
+1. View all words added from the Dictionary screen
+2. Drag and drop words to reorder them into the correct sentence structure
+3. Remove unwanted words
+4. Create multiple sentences across multiple pages
+5. Save the complete document to the cloud (stored under user's account)
+6. Load previously saved documents for editing
+
+---
+
+#### Screen 3: Video Rečenica (Video Sentence Player) - "3 dodaj rijeci recenica.png"
+**Purpose:** Play all the sign videos for your sentence in sequence, with visual highlighting.
+
+**Key Elements:**
+- **Left side (60%):** Large video player showing the current word's sign video
+- **Right side (40%):** Sentence panel showing:
+  - Complete sentence with all words listed
+  - Current word being played is **highlighted/marked**
+  - Sentence navigation controls
+- **Playback controls:**
+  - Play/Pause
+  - Next/Previous word
+  - Speed control
+  - Loop options
+
+**User Actions:**
+1. Load a sentence from Znakopis or Cloud
+2. Click play to start sequential video playback
+3. Watch as each word's sign video plays in order
+4. See visual highlighting on the current word being signed
+5. Control playback (pause, skip, adjust speed)
+6. Navigate between different sentences/pages in the document
+
+---
+
+### 8.1 Complete User Workflow (End-to-End)
+
+**Step 1: Build a Sentence (Riječi → Znakopis)**
+1. User navigates to **"Riječi"** (Dictionary)
+2. User searches/browses for words they want to use
+3. User clicks **"Dodaj"** on each word card to add it to their sentence
+   - Words accumulate in a sentence builder area (visible at top)
+4. User can click **"Info"** on any word to preview its sign video
+5. After adding all desired words, user navigates to **"Znakopis"**
+6. In Znakopis, user sees all added words as draggable tokens
+7. User drags and drops words to arrange them in correct order
+8. User can remove unwanted words
+9. User can create additional sentences on new pages
+10. User clicks **"Spremi"** (Save) to save the document to cloud
+    - Document is stored under the user's account in the portal
+
+**Step 2: Review and Play (Znakopis → Video Rečenica)**
+1. User navigates to **"Video rečenica"** (Video Sentence)
+2. User loads their saved sentence/document
+3. Sentence appears in the right panel with all words listed
+4. User clicks **Play**
+5. Video player shows each word's sign video in sequence
+6. Current word is **highlighted** in the sentence list
+7. User can control playback, adjust speed, or navigate between sentences
+
+**Step 3: Manage Documents (Oblak)**
+1. User navigates to **"Oblak"** (Cloud)
+2. User sees all their saved documents
+3. User can:
+   - Load a document back into Znakopis for editing
+   - Delete documents
+   - Share documents (generate link)
+   - View document metadata (creation date, page count, etc.)
+
+---
+
+### 8.2 Critical Implementation Requirements
+
+**Sentence State Management:**
+- Sentence state must persist across all three screens (Riječi → Znakopis → Video Rečenica)
+- When user adds words in Riječi, they must appear in Znakopis
+- When user saves in Znakopis, document must be available in Video Rečenica and Oblak
+- Use Zustand store to maintain sentence/document state globally
+
+**Video Synchronization:**
+- In Video Rečenica, video playback must be synchronized with word highlighting
+- When video for word N finishes, automatically start video for word N+1
+- Highlight must move to the current word being played
+- Smooth transitions between videos (preload next video)
+
+**Document Structure:**
+- Documents can have multiple pages
+- Each page can have multiple sentences
+- Each sentence is a sequence of word tokens
+- Tokens maintain reference to original Term (for video lookup)
+- Token order is preserved and editable
+
+**Cloud Storage:**
+- All saved documents are associated with the logged-in user
+- Documents persist in database (Document → DocumentPage → Sentence → SentenceToken)
+- Users can only see/edit their own documents (unless shared)
+- Documents can be loaded back into Znakopis for editing

 ---

@@ -1331,21 +1551,63 @@ npx shadcn-ui@latest add card

 ## 12. Success Criteria

-### Functional Requirements ✅
- [ ] Users can browse and search dictionary with filters
- [ ] Word detail modal displays video and metadata
- [ ] Users can build sentences by adding words
+### Core Functionality Requirements (CRITICAL) ✅
+
+**Screen 1: Riječi (Dictionary)**
+- [ ] Dictionary displays grid of word cards with icons
+- [ ] Each card has "Dodaj" (Add) and "Info" buttons
+- [ ] Clicking "Dodaj" adds word to current sentence (visible at top of page)
+- [ ] Clicking "Info" opens modal with sign video that auto-plays
+- [ ] Search and filter controls work (word type, CEFR level)
+- [ ] Words are color-coded by difficulty level
+
+**Screen 2: Znakopis (Sentence Builder)**
+- [ ] All words added from Dictionary appear as draggable tokens
 - [ ] Tokens can be reordered via drag-and-drop
- [ ] Sentences can be saved to documents
- [ ] Documents can be loaded from cloud
- [ ] Video sentence player works with sequential playback
+- [ ] Tokens can be removed
+- [ ] Right panel shows "Popis rečenica" (Sentence List)
+- [ ] Users can create multiple sentences across multiple pages
+- [ ] "Spremi" (Save) button saves document to cloud under user's account
+- [ ] "Učitajte dokument" (Load Document) loads previously saved documents
+- [ ] Page navigation works (e.g., "1 / 2 stranica")
+
+**Screen 3: Video Rečenica (Video Player)**
+- [ ] Left side shows large video player (60% width)
+- [ ] Right side shows sentence panel with all words (40% width)
+- [ ] Clicking Play starts sequential video playback
+- [ ] Videos play in order, one after another
+- [ ] Current word being signed is **highlighted** in the sentence list
+- [ ] Highlighting moves automatically as videos progress
+- [ ] Playback controls work (play, pause, next, previous)
+- [ ] Speed control and loop options work
+- [ ] Videos transition smoothly (preload next video)
+
+**Cross-Screen Integration**
+- [ ] Sentence state persists from Riječi → Znakopis → Video Rečenica
+- [ ] Documents saved in Znakopis appear in Oblak (Cloud)
+- [ ] Documents loaded from Oblak can be edited in Znakopis
+- [ ] Documents loaded from Oblak can be played in Video Rečenica
+
+**Authentication & User Management**
 - [ ] Admin can login with credentials
 - [ ] Admin can create/edit/delete local users
 - [ ] Admin can reset user passwords
 - [ ] Admin can activate/deactivate users
 - [ ] Regular users can login with their credentials
- [ ] Cloud document management works
+- [ ] Documents are associated with logged-in user
+- [ ] Users can only see their own documents (unless shared)
+
+**Cloud Document Management (Oblak)**
+- [ ] Users can view all their saved documents
+- [ ] Documents show metadata (title, creation date, page count)
+- [ ] Users can load documents into Znakopis
+- [ ] Users can delete documents
+- [ ] Users can share documents (generate link)
+
+**Additional Features**
 - [ ] Comments and bug reports can be submitted
+- [ ] Help page displays usage documentation
+- [ ] Community features work

 ### Visual Requirements ✅
 - [ ] UI matches screenshots pixel-perfect