Add comprehensive project documentation
- 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
This commit is contained in:
362
original/project1.md
Normal file
362
original/project1.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user