{"id":33492070,"url":"https://github.com/bartekmp/osmosmjerka","last_synced_at":"2026-03-18T00:07:34.395Z","repository":{"id":300983151,"uuid":"1007777199","full_name":"bartekmp/osmosmjerka","owner":"bartekmp","description":"Web-based word search game with a language learning twist.","archived":false,"fork":false,"pushed_at":"2026-03-10T18:52:56.000Z","size":98207,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T22:39:44.700Z","etag":null,"topics":["fastapi","game","react","webapp","wordsearch","wordsearch-creator","wordsearch-puzzle"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bartekmp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-24T14:09:32.000Z","updated_at":"2026-03-10T16:53:34.000Z","dependencies_parsed_at":"2025-07-17T07:36:17.998Z","dependency_job_id":"d5a7be65-5902-4485-839c-edfbc4767cab","html_url":"https://github.com/bartekmp/osmosmjerka","commit_stats":null,"previous_names":["bartekmp/osmosmjerka"],"tags_count":125,"template":false,"template_full_name":null,"purl":"pkg:github/bartekmp/osmosmjerka","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartekmp%2Fosmosmjerka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartekmp%2Fosmosmjerka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartekmp%2Fosmosmjerka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartekmp%2Fosmosmjerka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bartekmp","download_url":"https://codeload.github.com/bartekmp/osmosmjerka/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartekmp%2Fosmosmjerka/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30636826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T23:56:54.546Z","status":"ssl_error","status_checked_at":"2026-03-17T23:56:28.952Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","game","react","webapp","wordsearch","wordsearch-creator","wordsearch-puzzle"],"created_at":"2025-11-25T19:05:30.158Z","updated_at":"2026-03-18T00:07:34.375Z","avatar_url":"https://github.com/bartekmp.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"frontend/public/android-chrome-192x192.png\" alt=\"Osmosmjerka Logo\" width=\"128\" height=\"128\"\u003e\n  \u003ch1\u003eOsmosmjerka\u003c/h1\u003e\n  \n  \u003cp\u003eA feature-rich web-based word search game with language learning capabilities\u003c/p\u003e\n  \n  [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n  [![CI](https://github.com/bartekmp/osmosmjerka/actions/workflows/ci-pipeline.yml/badge.svg)](https://github.com/bartekmp/osmosmjerka/actions/workflows/ci-pipeline.yml)\n  [![React](https://img.shields.io/badge/React-19.1.1-61dafb?logo=react)](https://react.dev/)\n  [![FastAPI](https://img.shields.io/badge/FastAPI-0.127.0-009688?logo=fastapi)](https://fastapi.tiangolo.com/)\n  [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-18-336791?logo=postgresql)](https://www.postgresql.org/)\n  [![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fbartekmp%2Fosmosmjerka-blue?logo=docker)](https://github.com/bartekmp/osmosmjerka/pkgs/container/osmosmjerka)\n  \n  **[🎮 Live Demo](https://osmosmjerka.app/)** • Use `demo` / `demo` to login\n  \n\u003c/div\u003e\n\n---\n\n## 📑 Table of Contents\n\n- [About](#-about)\n- [Key Features](#-key-features)\n- [How to Play](#-how-to-play)\n- [Quick Start](#-quick-start)\n  - [Installation](#installation)\n  - [Cloud Deployment](#cloud-deployment)\n  - [Development Mode](#development-mode)\n- [Configuration](#️-configuration)\n- [Data Management](#-data-management)\n- [Admin Panel](#️-admin-panel)\n- [HTTPS Support](#-https-support)\n- [Contributing](#-contributing)\n- [Roadmap](#️-roadmap)\n- [License](#-license)\n\n## 📖 About\n\n[Osmosmjerka](https://hr.wikipedia.org/wiki/Osmosmjerka) (*Croatian for \"eight-direction word search puzzle\"*) is a modern, multilingual [word search game](https://en.wikipedia.org/wiki/Word_search) designed for language learners. Each puzzle is themed with categorized phrases that include translations, turning gameplay into an engaging [flashcard](https://en.wikipedia.org/wiki/Flashcard)-style learning experience.\n\n**Tech Stack:** React • FastAPI • PostgreSQL\n\n## ✨ Key Features\n\n### Game Features\n- 🎯 **Smart Puzzle Generation** - Intelligent algorithm creates challenging grids with maximized phrase intersections ([Algorithm Details](ALGORITHM.md))\n- 🌍 **Multi-language Support** - Full i18n with English, Croatian, and Polish (easily extensible)\n- 🎨 **Dark/Light Themes** - Comfortable viewing in any lighting condition\n- 💾 **Auto-save Progress** - Resume your game exactly where you left off\n- 📤 **Export Puzzles** - Download as DOCX or PNG for offline use\n- 💡 **Progressive Hints** - Multi-level assistance system when you're stuck\n- 📊 **Statistics \u0026 Scoring** - Track your performance and improvement over time\n- 📱 **Responsive Design** - Optimized for desktop, tablet, and mobile devices\n\n### Admin Features\n- 👥 **User Management** - Role-based access control (root admin, admin, user)\n- 🗂️ **Language Sets** - Organize phrases into separate language collections\n- 📝 **Phrase Database** - Comprehensive management with import/export and duplicate detection\n- ⚡ **Batch Operations** - Bulk editing, category management, multi-select actions\n- 🔄 **Data Import/Export** - Support for TXT and CSV file formats, plus copy-paste modal for quick additions\n- 🔍 **Duplicate Management** - Automatic detection and prevention of duplicate phrases\n\n### Education Features\n- 🍎 **Teacher Mode** - Create custom puzzles, manage study groups, and assign work to students\n- 📚 **My Study Dashboard** - Students can track pending and completed assignments\n- 📈 **Progress Monitoring** - Teachers can view student performance and export results as CSV\n\n## 🎮 How to Play\n\nFind all phrases hidden in the grid! Phrases can appear in eight directions: horizontal, vertical, diagonal, and reversed. Click or swipe to select words, and watch as translations appear when you find them.\n\n### Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"docs/assets/osmosmjerka-game.gif\" alt=\"Gameplay\"\u003e\u003cbr\u003e\n      \u003cem\u003eFinding phrases in action\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"docs/assets/osmosmjerka-new-round.png\" alt=\"New Round\"\u003e\u003cbr\u003e\n      \u003cem\u003eStarting a new puzzle\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"docs/assets/osmosmjerka-won-round.png\" alt=\"Victory\"\u003e\u003cbr\u003e\n      \u003cem\u003ePuzzle completed with visual effects!\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"docs/assets/osmosmjerka-nightmode.png\" alt=\"Dark Mode\"\u003e\u003cbr\u003e\n      \u003cem\u003eDark theme for comfortable viewing\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Docker\n- PostgreSQL database\n- Node.js \u0026 npm (for development)\n\n### Installation\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/bartekmp/osmosmjerka.git\ncd osmosmjerka\n```\n\n2. **Configure environment**\n```bash\ncp .env.example .env\n# Edit .env with your settings (see Configuration section)\n```\n\n3. **Set up PostgreSQL**\n   \n   Deploy using the [example K8s YAML](/helpers/k8s-postgres.yaml) or use your existing instance. Create the database and user account, then update `POSTGRES_*` variables in `.env`.\n\n4. **Build and run with Docker**\n```bash\ndocker build -t osmosmjerka --build-arg VERSION=v1.33.0 .\ndocker run --rm -d -p 8085:8085 --name osmosmjerka osmosmjerka\n```\n\n5. **Access the application**\n   \n   Open `http://localhost:8085` in your browser.\n\n### Cloud Deployment\n\nOsmosmjerka is **cloud-ready** and can be deployed in various environments:\n\n#### Standalone Container\nRun as a single Docker container on any cloud platform (AWS ECS, Google Cloud Run, Azure Container Instances, etc.):\n\n```bash\ndocker run -d -p 8085:8085 \\\n  -e ADMIN_USERNAME=admin \\\n  -e ADMIN_PASSWORD_HASH=\u003cyour_hash\u003e \\\n  -e ADMIN_SECRET_KEY=\u003cyour_secret\u003e \\\n  -e POSTGRES_HOST=\u003cyour_db_host\u003e \\\n  -e POSTGRES_USER=\u003cdb_user\u003e \\\n  -e POSTGRES_PASSWORD=\u003cdb_pass\u003e \\\n  -e POSTGRES_DATABASE=osmosmjerka \\\n  osmosmjerka:latest\n```\n\n#### Kubernetes Cluster\nDeploy to Kubernetes using the provided example manifest:\n\n```bash\n# Review and customize the deployment\ncp osmosmjerka-deployment.yaml.example osmosmjerka-deployment.yaml\n# Edit with your configuration (secrets, resources, etc.)\nvim osmosmjerka-deployment.yaml\n\n# Deploy to your cluster\nkubectl apply -f osmosmjerka-deployment.yaml\n```\n\nThe example manifest includes:\n- Deployment with configurable replicas\n- Service definition\n- ConfigMap for environment variables\n- Secret management for sensitive data\n- Health check probes\n- Resource limits and requests\n\nSee [`osmosmjerka-deployment.yaml.example`](osmosmjerka-deployment.yaml.example) for the complete configuration template.\n\n### Development Mode\n\nFor development with hot reload:\n\n```bash\n./start-dev-env-watch.sh\n```\n\nThis starts:\n- Frontend: `http://localhost:3210` (Vite dev server)\n- Backend API: `http://localhost:8085`\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development setup and workflows.\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nEnvironment variables are used to configure the application. You can either set them in your shell, use the `.env` file in the root project directory, or when deploying a locally built container use `-e` switches to provide each variable. \n\nSupported variables:\n\n```bash\n# Admin Credentials (required)\nADMIN_USERNAME=admin\nADMIN_PASSWORD_HASH=\u003cbcrypt_hash\u003e  # See below for generation\nADMIN_SECRET_KEY=\u003cyour_secret_key\u003e  # Secret key for JWT token signing\n\n# Database (required)\nPOSTGRES_USER=osmosmjerka\nPOSTGRES_PASSWORD=\u003cdb_password\u003e\nPOSTGRES_DATABASE=osmosmjerka\nPOSTGRES_HOST=localhost\nPOSTGRES_PORT=5432\n\n# Database Connection Pool (optional)\nDB_POOL_SIZE=10          # Number of connections to maintain in the pool (default: 10)\nDB_MAX_OVERFLOW=5        # Maximum number of connections to create beyond pool_size (default: 5)\nDB_POOL_TIMEOUT=30      # Timeout in seconds for getting a connection from the pool (default: 30)\n\n# Logging Configuration (optional)\nLOG_DEVELOPMENT_MODE=false  # Enable human-readable logs with colors (default: false)\nLOG_LEVEL=INFO              # Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)\nLOG_COLORS=true             # Enable colored output in development mode (default: true)\n```\n\n### Generate Admin Password Hash\n\nUse this command to create a bcrypt password hash:\n\n```bash\npython3 -c \"import bcrypt; import getpass; pwd=getpass.getpass('Password: ').encode(); print(bcrypt.hashpw(pwd, bcrypt.gensalt()).decode())\"\n```\n\n## Logging \u0026 Monitoring\n\nOsmosmjerka features a comprehensive hybrid logging system optimized for both development and production:\n\n- **Development Mode**: Human-readable plain text logs with color coding\n- **Production Mode**: Structured JSON logs for Kubernetes and log aggregation\n- **Structured Logging**: All logs include contextual data (user_id, session_id, etc.)\n- **Exception Tracking**: Full stack traces with context for all errors\n- **stdout/stderr Separation**: INFO/DEBUG to stdout, WARNING/ERROR/CRITICAL to stderr\n\n**Quick Example:**\n```bash\n# View logs in Kubernetes\nkubectl logs deployment/osmosmjerka-backend | jq 'select(.level==\"ERROR\")'\n```\n\n## 📚 Data Management\n\n### Import Phrases\n\nThe admin panel provides multiple ways to add phrases to your database:\n\n#### File Upload\nUpload phrases using TXT or CSV files via the admin panel (`/admin`):\n\n**Format:** `phrase;translation;categories`\n\n**Example:**\n```\nPYTHON;Programming language;Technology Programming\nALGORITHM;Step-by-step procedure;Computer Science\nGRAMMAR;Language rules;Language Learning\n```\n\n#### Copy-Paste Modal\nPrefer direct input? Use the copy-paste modal in the admin panel to paste blocks of phrases directly:\n- No need to create files first\n- Paste multiple lines at once\n- Same format as file uploads: `phrase;translation;categories`\n- Real-time validation before submission\n- Ideal for quick additions or updates\n\n#### Duplicate Management\nOsmosmjerka automatically handles duplicates intelligently:\n- **Automatic Detection** - Identifies duplicate phrases during import\n- **Smart Prevention** - Prevents duplicate entries in the database (phrase field is the primary key)\n- **Clear Reporting** - Shows which phrases were skipped due to duplication\n- **Safe Imports** - You can re-import the same file without creating duplicates\n- **Merge Support** - Update existing phrases by importing with the same phrase text\n\n**Sample Data:** Check the `example/words.txt` file for Croatian-Polish phrases.\n\n### Language Sets\n\nOrganize phrases into separate collections (e.g., Croatian-English, Spanish-French). Configure via the admin panel under \"Language Sets Management\".\n\n![Language Set Management](docs/assets/osmosmjerka-language-set-mgmt.gif)\n\n## Private Phrase Lists\n\nOrganize and manage custom phrase collections for targeted learning with the **Learn This Later** feature.\n\n### Overview\n\nCreate private phrase lists to save words and expressions you want to practice later. Each phrase added via the **Learn This Later** button during gameplay is automatically saved to your personal collection for future study. You can also create your own lists and import phrases from external sources. **Learn This Later** is a built-in private list and cannot be removed.\n\n### Features\n\n#### 💾 Learn This Later Button\n\n![Learn This Later](docs/assets/osmosmjerka-learn-this-later-add.png)\n\nWhile playing, save interesting phrases directly from the game grid:\n- Click and highlight any found phrase on the phrase list view\n- Click the \"Add X selected to Learn This Later\" button\n- Access saved phrases anytime from the \"My Lists\" tab\n- Generate a puzzle using only the phrases from your private list\n- Continue playing without interruption\n\n#### 📋 List Management\n\n![List Management](docs/assets/osmosmjerka-list-management-phrases.png)\n\nCreate and organize multiple themed collections:\n- **Create Lists** - Organize phrases by topic, difficulty, or learning goal\n- **Rename Lists** - Update list names as your learning focus evolves\n- **Delete Lists** - Remove lists you no longer need (phrases are deleted)\n- **Switch Between Lists** - Easily navigate between multiple collections\n- **Share Lists** - Share your lists with other users\n- **Review Lists** - Review your lists and their contents\n\n#### 📤 Batch Import\n\nImport phrases in bulk from external sources (up to 1000 phrases per import):\n\n**CSV Format:**\n```csv\nsource,translation,context,category\nhello,hola,greeting,Basic\ngoodbye,adiós,farewell,Basic\nthank you,gracias,gratitude,Polite\n```\n\n**Import Process:**\n1. Click the **Import** button in List Management\n2. Upload a CSV file with phrases\n3. Preview the phrases to be imported\n4. Confirm to add all phrases to your selected list\n\n**Notes:**\n- Maximum 1000 phrases per import\n- Duplicate phrases within the import are automatically removed\n- `source` and `translation` fields are required\n- `context` and `category` fields are optional\n\n#### 🤝 List Sharing\n\nCollaborate with other learners by sharing phrase lists:\n\n**Share a List:**\n1. Open the **Share** dialog from List Management\n2. Enter the username of the person you want to share with\n3. Choose permission level:\n   - **Read** - View phrases only, cannot modify\n   - **Write** - View and add/edit/delete phrases\n4. Click **Share** to grant access\n\n**View Shared Lists:**\n- Lists shared by others appear in the **Shared With Me** section\n- Permission level is displayed next to each shared list\n- Access shared lists just like your own (within permission limits)\n\n**Unshare a List:**\n- Select a list by selecting it in the \"My Lists\" tab, go to the second tab\n- Open the **Share List** dialog\n- Click **Remove** next to the user you want to revoke access from\n- User immediately loses access to the list\n\n#### 📊 Statistics\n\nTrack your learning progress with detailed statistics:\n\n**Per-List Statistics:**\n- Total phrase count\n- Most frequently used phrases\n- Last updated timestamp\n- Growth over time\n\n**Global Statistics:**\n- Total phrases across all lists\n- Most active lists\n- Learning velocity metrics\n- Category distribution\n\nAccess statistics from the **Statistics** button in List Management.\n\n## 🛠️ Admin Panel\n\nAccess the admin panel at `/admin` with your configured admin credentials.\n\n![Admin Dashboard](docs/assets/osmosmjerka-admin-view.png)\n\n### User Roles\n\n- **Root Administrator** - Full system access, user management, system settings\n- **Administrative Users** - Database management, no user creation/deletion\n- **Regular Users** - Game access only\n\n### Features Overview\n\n#### Phrase Database Management\n\n![Database Management](docs/assets/osmosmjerka-admin.gif)\n\n- **Browse \u0026 Search** - Advanced filtering, pagination, and search across phrases/translations\n- **Inline Editing** - Edit phrases, translations, and categories directly\n- **Batch Operations** - Multi-select for bulk delete and category management\n- **File Import** - Support for TXT and CSV formats for uploading phrases into the database\n- **Copy-Paste Modal** - Quick phrase addition by pasting blocks of text directly (no files needed)\n- **Download** - Download the entire database or just filtered rows as a TXT file\n- **Duplicate Detection** - Automatic identification and prevention of duplicate entries\n- **Data Validation** - Real-time validation with clear error reporting\n\n#### User Management\n\n![User Management](docs/assets/osmosmjerka-user-mgmt.gif)\n\n*Available to root administrators only*\n\n- Create and manage user accounts\n- Role assignment and permissions\n- Password reset functionality\n- User profile customization\n\n#### Language Sets Management\n\n![Language Sets](docs/assets/osmosmjerka-language-set-mgmt.gif)\n\nOrganize phrases into separate collections for different language pairs or themes:\n\n- Create multiple language collections (e.g., Croatian-English, Spanish-French)\n- Set default ignored categories per language set\n- Bulk operations for moving phrases between sets\n- Configure default language set for new users\n- Export/import entire language sets\n\n#### System Settings\n\n![System Settings](docs/assets/osmosmjerka-system-settings.png)\n\n*Root administrators only*\n\nGlobal configuration for game features:\n- **Progressive Hints** - Enable/disable multi-level hint system\n- **Scoring System** - Toggle statistics tracking and performance metrics\n- **User Overrides** - Allow individual users to override global settings\n\n### Game Features\n\n#### Progressive Hints\n\n![Game Features](docs/assets/osmosmjerka-main-game-features.gif)\n\nA multi-level assistance system that helps players solve challenging puzzles:\n- First letter hints reveal starting characters\n- Progressive disclosure maintains challenge balance\n- Configurable globally or per-user\n- Visual feedback in the grid\n\n#### Scoring \u0026 Statistics\n\n![Statistics Dashboard](docs/assets/osmosmjerka-stats-dashboard.gif)\n\nTrack and analyze player performance:\n- Completion time and accuracy metrics\n- Hint usage patterns\n- Category-specific performance\n- Game completion rates across difficulty levels\n\n## 🍎 Education \u0026 Teacher Mode\n\nOsmosmjerka includes powerful tools for educators to manage classes, create custom assignments, and track student progress.\n\n### For Teachers\n\n*Accessed via the \"Teacher Tools\" section in the Dashboard.*\n\n![Teacher Dashboard](docs/assets/osmosmjerka-teacher-mode-puzzle-view.png)\n_Manage your puzzles, assignments, and class groups in one place_\n\n*   **Custom Puzzle Creation**: Design puzzles tailored to your lesson plan.\n    *   **Content Control**: Select specific phrases from your database or entire language categories.\n    *   **Game Rules**: Configure difficulty, toggle hints, enable/disable translations, and set timers.\n    *   **Auto-Expiration**: Set assignments to automatically expire after a set number of days.\n\n*   **Class Management**: Organize your students using **Study Groups**.\n    ![Teacher Group View](docs/assets/osmosmjerka-teacher-mode-create-group.gif)\n    *   **Simple Onboarding**: Create a group and notify students about it. Students are added to your class roster upon acceptance right from their personal dashboard.\n    *   **Bulk Assignments**: Assign a puzzle to an entire group with a single click.\n\n*   **Flexible Assignment Options**:\n    ![Teacher Assignments](docs/assets/osmosmjerka-teacher-mode-create-puzzle.gif)\n    *   **Public Links**: Generate a shareable link that anyone can play without logging in.\n    *   **Private Assignments**: Assign puzzles directly to specific students or groups. These appear securely in their personal dashboard.\n\n*   **Progress Tracking**:\n    ![Teacher Progress View](docs/assets/osmosmjerka-teacher-mode-review-results.gif)\n    *   **Session Monitoring**: View detailed reports on who played your puzzles, their scores, found phrases, and completion times.\n    *   **Review Translations**: Teachers can check student translation inputs if manual entry was required.\n    *   **Data Export**: Download session data as CSV files for grading and analysis.\n\n### For Students\n\n*Accessed via the \"Learning\" section in the Dashboard.*\n\n![Student Study View](docs/assets/osmosmjerka-my-study-puzzle-view.png)\n_A clear, organized view of all assigned work_\n\n*   **\"My Study\" Dashboard**: A dedicated space for all teacher-assigned activities.\n    *   **To-Do List**: Assignments are clearly organized into **\"New Puzzles\"** (Pending) and **\"Solved Puzzles\"** (Completed).\n    *   **Status Indicators**: \"New\" and \"Solved\" chips help students prioritize their work.\n    *   **Assignment Details**: View the creator's name and assignment date for each puzzle.\n\n* **Study Group Management**: Students review and manage their study groups.\n![Student Group View](docs/assets/osmosmjerka-my-study-accept-invite.gif)\n\n*   **Integrated Learning**: Puzzles assigned by teachers behave just like standard games but the teachers can track progress specific to the assignment and review student's translation inputs.\n![Student Play View](docs/assets/osmosmjerka-my-study-play-puzzle.gif)\n\n## 🔒 HTTPS Support\n\nThe API server ([uvicorn](https://www.uvicorn.org/)) supports SSL/TLS for secure connections.\n\n### Using SSL Certificates\n\nStore certificates in the `backend` directory and update the Docker `CMD`:\n\n```bash\nCMD [\"uvicorn\", \"app:app\", \"--host\", \"0.0.0.0\", \"--port\", \"443\", \n     \"--ssl-keyfile=privkey.pem\", \"--ssl-certfile=fullchain.pem\"]\n```\n\n### Generate Self-Signed Certificate (Development)\n\n```bash\nopenssl req -x509 -nodes -days 365 -newkey rsa:2048 \\\n  -keyout privkey.pem -out fullchain.pem -subj \"/CN=localhost\"\n```\n\n**Note:** Self-signed certificates will trigger browser warnings. For production, use certificates from [Let's Encrypt](https://letsencrypt.org/).\n\n## 🤝 Contributing\n\nContributions are welcome! Please check out:\n- [DEVELOPMENT.md](DEVELOPMENT.md) - Development setup and workflows\n- [ALGORITHM.md](ALGORITHM.md) - Grid generation algorithm details\n\n### Adding New Languages\n\n1. Create a new JSON file in `frontend/src/locales/`\n2. Translate all entries based on existing language files\n3. Register the language in `frontend/src/i18n.js`\n\n## 🗺️ Roadmap\n\n- [ ] Integration with [Anki](https://apps.ankiweb.net/) for spaced repetition learning\n- [ ] Learning curve tracking\n- [ ] Crosswords puzzles\n- [x] Teacher mode - puzzles generated by the teacher to their students\n- [x] My Study - play puzzles assigned by teachers, manage your study groups\n- [x] Notifications - get notified of new assignments and other events\n\n\n## 📄 License\n\nLicensed under [Apache License 2.0](LICENSE)\n\n## 🙏 Acknowledgments\n\n- Word search puzzle concept: Traditional [Osmosmjerka](https://hr.wikipedia.org/wiki/Osmosmjerka)\n- Example Croatian-Polish phrase database included in `example/` folder\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eMade with ❤️ for language learners\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/bartekmp/osmosmjerka/issues\"\u003eReport Bug\u003c/a\u003e •\n    \u003ca href=\"https://github.com/bartekmp/osmosmjerka/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartekmp%2Fosmosmjerka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbartekmp%2Fosmosmjerka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartekmp%2Fosmosmjerka/lists"}