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

README.md

@@ -0,0 +1,181 @@
+# Znakovni.hr - Croatian Sign Language Web Application
+
+A modern web application for learning and using Croatian Sign Language (Hrvatski znakovni jezik). This is a proof-of-concept implementation designed to replicate the functionality of the original Znakovni.hr platform.
+
+## 🎯 Project Overview
+
+Znakovni.hr is a comprehensive platform that enables users to:
+- **Browse and search** a dictionary of Croatian sign language terms with video demonstrations
+- **Build sentences** using a visual sentence builder (Znakopis)
+- **Watch video playback** of complete sentences in sign language
+- **Save and manage** documents in the cloud
+- **Collaborate** through community features and feedback
+
+## 🚀 Technology Stack
+
+### Frontend
+- **React 18.2+** with TypeScript
+- **Vite 5+** for fast development and building
+- **Tailwind CSS 3+** for pixel-perfect styling
+- **shadcn/ui** for beautiful, accessible components
+- **Zustand** for lightweight state management
+- **Plyr** for video playback
+- **@dnd-kit** for drag-and-drop functionality
+- **React Router v6** for navigation
+
+### Backend
+- **Node.js 20 LTS** with Express.js
+- **TypeScript** for type safety
+- **Prisma 5+** as ORM with MySQL
+- **Passport.js** for authentication (Google, Microsoft, local)
+- **Multer** for file uploads
+
+### Database
+- **MySQL 8.0+** with Prisma ORM
+- Full-text search capabilities
+- Optimized for 1-2 concurrent users (PoC)
+
+### Storage
+- Local filesystem for media storage
+- `/uploads` directory structure for videos, icons, and documents
+
+## 📁 Project Structure
+
+```
+znakovni/
+├── packages/
+│   ├── frontend/          # React + Vite application
+│   │   ├── src/
+│   │   │   ├── components/   # Reusable UI components
+│   │   │   ├── pages/        # Route pages
+│   │   │   ├── stores/       # Zustand stores
+│   │   │   ├── lib/          # Utilities and API client
+│   │   │   └── types/        # TypeScript types
+│   │   └── package.json
+│   │
+│   └── backend/           # Express + TypeScript API
+│       ├── src/
+│       │   ├── routes/       # API route handlers
+│       │   ├── controllers/  # Business logic
+│       │   ├── middleware/   # Express middleware
+│       │   ├── services/     # External services
+│       │   └── lib/          # Utilities
+│       ├── prisma/           # Database schema and migrations
+│       ├── uploads/          # Local file storage
+│       └── package.json
+│
+├── original/              # Original specifications and screenshots
+├── main-plan.md          # Detailed implementation plan
+├── package.json          # Root package.json (workspace)
+└── pnpm-workspace.yaml   # pnpm workspace configuration
+```
+
+## 🛠️ Getting Started
+
+### Prerequisites
+
+- **Node.js 20 LTS** or higher
+- **pnpm** package manager
+- **MySQL 8.0+** database server
+- **Git** for version control
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone https://git.matijaturk.from.hr/johnny2211/znakovni.hr.git
+   cd znakovni
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pnpm install
+   ```
+
+3. **Configure environment variables**
+   ```bash
+   # Backend
+   cp packages/backend/.env.example packages/backend/.env
+   # Edit packages/backend/.env with your database credentials and OAuth keys
+   
+   # Frontend
+   cp packages/frontend/.env.example packages/frontend/.env
+   # Edit packages/frontend/.env with your API URL
+   ```
+
+4. **Set up the database**
+   ```bash
+   cd packages/backend
+   npx prisma migrate dev
+   npx prisma db seed
+   cd ../..
+   ```
+
+5. **Start development servers**
+   ```bash
+   pnpm dev
+   ```
+
+   This will start:
+   - Frontend: http://localhost:5173
+   - Backend: http://localhost:3000
+
+## 📚 Key Features
+
+### 1. Dictionary (Riječi)
+- Browse and search Croatian sign language terms
+- Filter by word type and CEFR level
+- View video demonstrations for each term
+- Add words to sentence builder
+
+### 2. Sentence Builder (Znakopis)
+- Build sentences by adding words from the dictionary
+- Drag-and-drop to reorder tokens
+- Multi-page document support
+- Save documents to the cloud
+
+### 3. Video Sentence Player (Video rečenica)
+- Sequential video playback of complete sentences
+- Synchronized token highlighting
+- Playback controls (play, pause, speed, loop)
+
+### 4. Cloud Storage (Oblak)
+- Save and manage documents
+- Share documents with others
+- Load documents into the sentence builder
+
+### 5. Community Features
+- Submit comments and feedback
+- Report bugs and issues
+- Access help documentation
+
+## 🔐 Authentication
+
+The application supports multiple authentication methods:
+- **Email/Password** - Traditional local authentication
+- **Google OAuth** - Sign in with Google account
+- **Microsoft OAuth** - Sign in with Microsoft account
+
+## 📖 Documentation
+
+For detailed implementation information, see:
+- **[main-plan.md](./main-plan.md)** - Complete implementation plan with technical specifications
+- **[original/project1.md](./original/project1.md)** - Original functional specifications
+- **[original/project2.md](./original/project2.md)** - Replication requirements
+
+## 🚢 Deployment
+
+See the [Deployment Guide](./main-plan.md#10-deployment-guide-poc) in main-plan.md for detailed deployment instructions.
+
+## 📄 License
+
+This project is a proof-of-concept implementation for educational purposes.
+
+## 👥 Contributing
+
+This is a proof-of-concept project. For questions or suggestions, please use the bug report feature within the application.
+
+## 🙏 Acknowledgments
+
+This project aims to support the Croatian deaf and hard-of-hearing community by providing accessible tools for learning and using Croatian Sign Language.
+

original/project1.md

@@ -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
+

original/project2.md

@@ -0,0 +1,241 @@
+# 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.