# Znakovni.hr – Full Application Replication Specification

## Purpose
This document specifies the **exact functionality, structure, and behavior** of the Znakovni.hr web application.
The goal is to enable AI programming agents to design and implement a **functionally identical copy** of the platform,
including UX flows, features, and system architecture.

Explicit permission has been granted by the original author to replicate the application for demonstration,
research, and AI capability showcasing purposes.

---

## 1. Application Overview

Znakovni.hr is a **web-based Croatian Sign Language (HZJ) platform** that provides:
- A video-based sign language dictionary
- Sentence construction tools using signs
- Video sentence playback
- User accounts and cloud storage

The platform functions as a **learning tool, reference dictionary, and sentence composition environment**.

---

## 2. Main Navigation & Screens

### 2.1 Sidebar Navigation
Persistent left sidebar with the following items:

- Početna (Home)
- Riječi (Dictionary)
- Znakopis (Sentence Builder)
- Video rečenica (Video Sentence Player)
- Oblak (Cloud Documents)
- Korištenje aplikacije (Help)
- Zajednica (Community)
- Komentari (Comments)
- Prijavi grešku (Bug Report)
- Sign in / Sign out

Sidebar is visible on all authenticated pages.

---

## 3. Screens & Functionality

### 3.1 Home (Početna)
- Intro headline: “Tvoj put u svijet znakovnog jezika”
- Feature overview cards:
  - Dictionary
  - Sentence composition (Znakopis)
  - Video sentences
  - Cloud documents

Static informational screen.

---

### 3.2 Dictionary (Riječi)

#### Features
- Free-text search
- Filters:
  - Word type
  - CEFR level (A1–C2)
- Paginated grid of word cards

#### Word Card
Each card includes:
- Icon representation
- Word label
- Difficulty color indicator
- Actions:
  - Add to sentence
  - Info

#### Word Detail
- Embedded sign video
- Linguistic metadata
- Usage context

---

### 3.3 Znakopis (Sentence Builder)

#### Purpose
Visual assembly of sign-language sentences.

#### Layout
- Sentence structure panel (left)
- Sentence description editor (right)

#### Features
- Add words from dictionary
- Reorder via drag or controls
- Remove words
- Multi-page sentence support
- Save as document

Documents may be saved locally or in cloud.

---

### 3.4 Video Rečenica (Video Sentence)

#### Purpose
Playback of complete sentences using video signs.

#### Layout
- Video player (left)
- Sentence structure view (right)

#### Controls
- Play / Pause
- Step navigation
- Repeat
- Speed adjustment (optional)

---

### 3.5 Oblak (Cloud Documents)

#### Purpose
Centralized storage of sentence documents.

#### Features
- Upload documents
- Save Znakopis documents
- Load and edit documents
- Document listing

---

### 3.6 Authentication

#### Login Methods
- Email/password
- Google OAuth
- Microsoft OAuth

#### Authenticated Capabilities
- Document persistence
- User-specific content
- Session continuity

---

## 4. Core Data Models

### User
- id
- email
- display_name
- auth_provider
- created_at

### Word
- id
- text
- word_type
- cefr_level
- icon_url
- video_url

### Sentence
- id
- user_id
- title
- created_at

### SentenceItem
- id
- sentence_id
- word_id
- position

### Document
- id
- user_id
- sentence_id
- storage_location
- updated_at

---

## 5. API Surface (Illustrative)

- GET /api/words
- GET /api/words/{id}
- POST /api/sentences
- PUT /api/sentences/{id}
- GET /api/documents
- POST /api/auth/login

---

## 6. Video Handling

- Short video clips per word
- Consistent framing
- Loop-ready
- Neutral background

Sentence playback = sequential video concatenation.

---

## 7. Non-Functional Requirements

- Desktop-first responsive UI
- High accessibility
- Fast filtering/search
- Stateless backend
- Secure auth

---

## 8. Architecture (Technology-Agnostic)

- SPA frontend
- REST backend
- Relational database
- Object storage for videos
- OAuth + JWT authentication

---

## 9. Functional Parity Criteria

- Dictionary search and filters
- Sentence creation
- Video sentence playback
- Cloud document storage
- Authentication

---

## 10. Scope

This document defines a **1:1 functional replication** of the Znakovni.hr application,
intended for controlled demonstration and AI-driven implementation planning.
