# project.md — Sign-Language Video Dictionary + Sentence Builder (Znakovni-style)

## Purpose
This file captures the **observed functionality** of the znakovni.hr web application (Croatian Sign Language portal) from the provided screenshots, so engineering agents can plan a comparable product.

### full copy
- Replicate **capabilities** and **branding**. I need 1to1 copy of the app.

---

## 1) Product summary (what it is)
A web app that provides:
1) A **sign-language dictionary**: browse and search words/terms and open an entry to view sign media.
2) A **sentence/document workspace** (“Znakopis”): build a sentence by selecting terms from the dictionary, save it as a document.
3) A **video sentence player** (“Video rečenica”): play a selected sentence/sequence as sign video; manage a sentence list and document pages.
4) A **cloud storage layer** (“Oblak”): store/load documents, likely behind login.
5) A **support/community area**: usage docs, community, comments, bug reporting.

From the screenshots, navigation is a **left sidebar** with core sections:
- **Početna** (Home)
- **Riječi** (Words / Dictionary)
- **Znakopis** (Sentence builder)
- **Video rečenica** (Video sentence)
- **Oblak** (Cloud)

A secondary “Portal za podršku” section appears in the sidebar:
- **Korištenje aplikacije**
- **Zajednica**
- **Komentari**
- **Prijavi grešku**
- External link: **znakovni.org**

Authentication UI shows **Sign in** when logged out and **Sign out + username** when logged in.

---

## 2) Screens (as observed)

### 2.1 Home (Početna)
Purpose: marketing/overview of capabilities.
Observed content blocks:
- Large brand header and a tagline (“your path into sign language world”).
- Feature cards/tiles that preview:
  - Dictionary browsing grid
  - Sentence building (Znakopis)
  - Video sentence playback
  - Cloud/integrations-style illustration

Functional requirements:
- Static content page
- Links to primary features

---

### 2.2 Dictionary (Riječi)
This is the primary discovery/browsing screen.

#### Layout
- **Top filter bar** with:
  - Text input: **Riječ** (word)
  - Dropdown: **Tip riječi** (word type)
  - Dropdown: **CEFR razina** (language level; example shows **A2**)
- **Top-right action cluster** includes:
  - Button with magnifier: **Traži** (search/submit)
  - Button: **Text** (likely toggles text-only vs icons/cards)
  - Button: **Reset** (clear filters)
- Main area: **grid of word cards**.

#### Word card (observed)
Each card shows:
- A simple **illustration/icon** representing the word
- The **word label** in a colored bar (colors vary per word)
- Two actions:
  - **Dodaj** (Add)
  - **Info** (Details)

Interpretation of actions:
- **Dodaj** likely adds the word to the current sentence/document in Znakopis / Video sentence workflow.
- **Info** opens a details view/modal with sign media (video), description, examples, metadata.

Functional requirements:
- Server-side / API-backed query with filtering
- Pagination or infinite scroll (not visible, but grid implies many items)
- Two presentation modes (cards with icons vs text list) toggled by “Text”
- Deterministic sorting (likely alphabetic by default)
- Per-term details

---

### 2.3 Sentence Builder (Znakopis)
A workspace for assembling words into sentences and saving them as documents.

Observed elements (from screenshots)
- A page titled similar to “Znakopis — Rečenica detaljno” (Sentence details)
- A right-side panel that shows:
  - **Popis rečenica** (Sentence list)
  - Page indicator like **1 / 0 stranica** (page count)
  - Controls resembling pagination / page navigation
  - Buttons/tabs at top: **Znakopis** and **Oblak**
  - A prompt like “Učitajte dokument” (Upload/load document) when no document loaded

Assumed core behavior:
- Users create a **document** containing one or more **sentences**.
- A sentence is assembled from selected dictionary entries.
- The document can be saved locally and/or to cloud.

Functional requirements:
- Create new document
- Add/remove/reorder tokens (words) in a sentence
- Save document; load document; export/import (likely)
- Maintain versioned pages or “pages” within a document

---

### 2.4 Video Sentence (Video rečenica)
A video player view to play the sign sequence corresponding to the constructed sentence.

Observed layout
- Left: **large video player** area with playback controls under it.
  - Controls include play/pause and additional buttons (likely speed, step, previous/next clip).
- Right: document area with:
  - **Popis rečenica** (Sentence list) in a large text box region
  - Tabs/buttons: **Znakopis** and **Oblak**
  - Pagination controls on the right (page number, next/prev)

Functional requirements:
- Given a sentence token list, create a **playlist** of videos (one per token) and play sequentially.
- Controls:
  - Play/pause
  - Next/previous token
  - (Recommended) speed control, loop, scrub/seek, fullscreen
- Sync player position with highlighted token in the sentence list.

---

### 2.5 Cloud (Oblak)
Based on UI labels, this is a storage layer for documents.

Functional requirements:
- List documents
- Load into Znakopis / Video sentence
- Save current document
- (Recommended) share via link, permissions, export

---

### 2.6 Authentication (Sign in)
Observed sign-in screen:
- “Sign in with your email address” (email-based login)
- “Sign in with your social account” with **Microsoft** and **Google** buttons
- “Sign up now” link

Functional requirements:
- Email + password or email magic link (choose one)
- OAuth for Microsoft and Google
- Account creation
- Session management

---

## 3) Core user flows

### Flow A — Find a sign for a word
1. Go to **Riječi**.
2. Filter by word text / type / CEFR.
3. Click **Info** on a card.
4. View sign media (video), metadata, and examples.

### Flow B — Build a sentence/document
1. Go to **Riječi**.
2. Click **Dodaj** on multiple cards.
3. Switch to **Znakopis**.
4. Reorder/remove tokens; optionally add punctuation.
5. Save document (local/cloud).

### Flow C — Play a sentence as sign video
1. Build or load a sentence in **Znakopis**.
2. Open **Video rečenica**.
3. Press play to see signs for each token in sequence.
4. Navigate pages/sentences.

### Flow D — Cloud document management
1. Sign in.
2. Open **Oblak**.
3. Create folders/tags (optional), load/save documents.

---

## 4) Data model (suggested)

### 4.1 Dictionary
**Term**
- id (uuid)
- word_text (string)
- normalized_text (string; for search)
- language (e.g., hr)
- word_type (enum; e.g., noun/verb/adj/phrase/etc.)
- cefr_level (enum: A1, A2, B1, B2, C1, C2)
- short_description (string, optional)
- tags (string[])
- icon_asset_id (nullable)
- created_at / updated_at

**TermMedia**
- id
- term_id
- kind (enum: video, image, illustration)
- url
- duration_ms (for video)
- width/height
- checksum

**TermExample** (optional)
- id
- term_id
- example_text
- notes

### 4.2 Documents / Znakopis
**Document**
- id
- owner_user_id (nullable if anonymous/local)
- title
- description
- visibility (private/shared/public)
- created_at / updated_at

**DocumentPage**
- id
- document_id
- page_index (int)
- title (optional)

**Sentence**
- id
- document_page_id
- sentence_index (int)
- raw_text (optional)

**SentenceToken**
- id
- sentence_id
- token_index (int)
- term_id (nullable if free-text)
- display_text
- punctuation (bool)

### 4.3 Community/support (optional)
- Comment/feedback
- Bug report

---

## 5) API surface (suggested)

### Dictionary
- `GET /api/terms?query=&type=&cefr=&page=`
- `GET /api/terms/{id}`
- `GET /api/terms/{id}/media`

### Documents
- `POST /api/documents` (create)
- `GET /api/documents` (list)
- `GET /api/documents/{id}` (full graph)
- `PUT /api/documents/{id}` (update metadata)
- `PUT /api/documents/{id}/content` (pages/sentences/tokens)
- `POST /api/documents/{id}/share` (optional)

### Playback helpers
- `POST /api/playlists` (sentence → resolved media playlist)
  - input: sentence_id or token list
  - output: ordered list of video URLs + metadata

---

## 6) Playback logic (Video sentence)
Recommended playlist resolution algorithm:
1. For each token, resolve `term_id`.
2. Choose primary media of kind=video.
3. Construct ordered playlist.
4. Player features:
   - preload next clip
   - auto-advance on end
   - handle missing media (skip with warning)
   - optional: loop sentence

---

## 7) UX components (reusable)
- Sidebar navigation with auth state (sign in/out)
- FilterBar component (text + dropdowns + reset)
- WordCard / WordRow (card and text modes)
- InfoModal (term details + video)
- TokenTray (current sentence tokens)
- DocumentBrowser (cloud)
- VideoPlayer with playlist
- SentenceList with token highlighting and page controls

---

## 8) Authentication & security
- OAuth (Google, Microsoft) + email auth
- RBAC:
  - anonymous: browse dictionary
  - authenticated: save/load cloud docs, comment, bug report
- Store secrets in vault; rotate keys
- Rate limit search and auth endpoints

---

## 9) Storage & delivery
- Relational DB: PostgreSQL
- Media storage: S3-compatible (S3, R2, MinIO)
- CDN for video assets
- Transcoding pipeline (recommended): upload → transcode to H.264 MP4 + WebM + poster frame

---

## 10) Non-functional requirements
- Performance: search results < 300ms p95 for common queries
- Accessibility: keyboard nav, visible focus, ARIA labels, captions where possible
- Internationalization-ready (hr now; extendable)
- Observability: logs, metrics, tracing

---

## 11) MVP scope (if building “parity-first”)
**MVP-1**
- Dictionary grid with filters (query/type/CEFR)
- Term details modal with video
- Add-to-sentence (“Dodaj”) into a simple token tray
- Znakopis page: edit/reorder tokens; save locally (browser storage)
- Video sentence page: playlist playback

**MVP-2**
- Login (Google/Microsoft/email)
- Cloud documents (create/list/load/save)
- Multi-page documents + sentence list

**MVP-3**
- Comments/feedback + bug reporting
- Sharing and permissions

---

## 12) Open questions (for agents to resolve)
- Exact meaning of “Text” toggle on Riječi page (list mode? free-text search within cards?)
- Definition and taxonomy of “Tip riječi” values
- Whether CEFR is per-term or per-example usage
- Document model: pages vs sentences; how “1 / 0 stranica” should behave
- Whether “Oblak” is a separate page *and* a tab within editors (observed as a tab)

---

## 13) References to provided screenshots (for context)
From screenshots you provided, the following are clearly visible:
- Home page with feature previews
- Dictionary page with filter bar and grid of word cards + “Dodaj/Info” actions
- Video sentence page with large player + sentence list panel
- Znakopis/Sentence details page with document loading prompt
- Sign-in page with email + Microsoft/Google