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:
181
README.md
Normal file
181
README.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user