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

   git clone https://git.matijaturk.from.hr/johnny2211/znakovni.hr.git
   cd znakovni
   

2. Install dependencies

   pnpm install
   

   When prompted to approve build scripts, select:

   • @prisma/client
   • @prisma/engines
   • bcrypt
   • esbuild
   • prisma

3. Generate Prisma Client

   cd packages/backend
   npx prisma generate
   cd ../..
   

4. Configure environment variables

   # 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

   cd packages/backend
   npx prisma migrate dev --name init
   npx prisma db seed
   cd ../..
   

6. Start development servers

   pnpm dev
   

   This will start:

   • Frontend: http://localhost:5173
   • Backend: http://localhost:3000

Verify Installation

Test the backend:

curl http://localhost:3000/api/health

You should see:

{"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 - Complete implementation plan with technical specifications
• original/project1.md - Original functional specifications
• original/project2.md - Replication requirements

🚢 Deployment

See the Deployment Guide 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.