znakovni.hr/README.md

# 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 (install with `npm install -g pnpm`)
- **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
   ```

   When prompted to approve build scripts, select:
   - `@prisma/client`
   - `@prisma/engines`
   - `bcrypt`
   - `esbuild`
   - `prisma`

3. **Generate Prisma Client**
   ```bash
   cd packages/backend
   npx prisma generate
   cd ../..
   ```

4. **Configure environment variables**
   ```bash
   # Backend
   cp packages/backend/.env.example packages/backend/.env
   # Edit packages/backend/.env with your database credentials
   # Update DATABASE_URL with your MySQL connection string

   # Frontend (optional)
   cp packages/frontend/.env.example packages/frontend/.env
   ```

5. **Set up the database**
   ```bash
   cd packages/backend
   npx prisma migrate dev --name init
   npx prisma db seed
   cd ../..
   ```

6. **Start development servers**
   ```bash
   pnpm dev
   ```

   This will start:
   - Frontend: http://localhost:5173
   - Backend: http://localhost:3000

### Verify Installation

Test the backend:
```bash
curl http://localhost:3000/api/health
```

You should see:
```json
{"status":"ok","message":"Backend is running!","timestamp":"..."}
```

Open http://localhost:5173 in your browser to see the frontend.

## 📋 Development Status

### ✅ Phase 0: Project Setup (COMPLETED)

**Deliverables:**
- ✅ Monorepo structure with pnpm workspaces
- ✅ Frontend (Vite + React + TypeScript) initialized
- ✅ Backend (Express + TypeScript) initialized
- ✅ Prisma with MySQL configured
- ✅ Tailwind CSS and shadcn/ui setup
- ✅ ESLint, Prettier, and TypeScript configs
- ✅ Environment variable templates
- ✅ Git repository and .gitignore
- ✅ Project compiles and runs successfully
- ✅ Database connection configured
- ✅ Basic "Hello World" on both ends

**What's Working:**
- Frontend builds and runs on http://localhost:5173
- Backend API runs on http://localhost:3000
- Health check endpoint: `GET /api/health`
- TypeScript compilation with strict mode
- Hot reload for development

### 🚧 Next Phase: Phase 1 - Core Infrastructure

**Upcoming Tasks:**
- Implement authentication (Passport.js with local, Google, Microsoft OAuth)
- Create user management system
- Build layout components (Sidebar, Header)
- Set up session management
- Implement CORS and security headers

## 📚 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.