znakovni.hr/original/project1.md

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