johnny2211
e38194a44c
- Add detailed implementation plan (main-plan.md) - Add professional README with project overview - Include original specifications and screenshots - Document technology stack and architecture - Provide setup and deployment instructions
363 lines
11 KiB
Markdown
363 lines
11 KiB
Markdown
# 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
|
|
|