{"id":32859989,"url":"https://github.com/jerynmathew/thurup","last_synced_at":"2026-05-06T19:02:10.645Z","repository":{"id":320184293,"uuid":"1081111163","full_name":"jerynmathew/thurup","owner":"jerynmathew","description":"Real-time multiplayer web implementation of the 28/56 card game with WebSocket support, bot players, and team-based scoring","archived":false,"fork":false,"pushed_at":"2025-10-22T12:52:30.000Z","size":523,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T13:10:00.010Z","etag":null,"topics":["fastapi","python","react","vitejs","websockets"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jerynmathew.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-22T10:25:30.000Z","updated_at":"2025-10-22T12:48:15.000Z","dependencies_parsed_at":"2025-10-22T13:10:09.498Z","dependency_job_id":"2fe038e9-68d9-4bac-8ac9-9ef85a6afefd","html_url":"https://github.com/jerynmathew/thurup","commit_stats":null,"previous_names":["jerynmathew/thurup"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jerynmathew/thurup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerynmathew%2Fthurup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerynmathew%2Fthurup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerynmathew%2Fthurup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerynmathew%2Fthurup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jerynmathew","download_url":"https://codeload.github.com/jerynmathew/thurup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerynmathew%2Fthurup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283393885,"owners_count":26828705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-08T02:00:06.281Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","python","react","vitejs","websockets"],"created_at":"2025-11-08T18:01:45.375Z","updated_at":"2025-11-08T18:02:40.311Z","avatar_url":"https://github.com/jerynmathew.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Thurup - 28/56 Card Game\n\nA modern, real-time multiplayer implementation of the classic 28/56 card game.\n\n## 🎮 Features\n\n- **Real-time Multiplayer**: Play with friends via WebSocket connections\n- **Bot AI**: Add computer opponents with configurable difficulty\n- **Game History**: Review past games with complete replay functionality\n- **Admin Dashboard**: Monitor server health and manage active games\n- **Persistent State**: Automatic game state saving and recovery\n- **Modern UI**: Beautiful, responsive interface built with React and TailwindCSS\n\n## 🚀 Quick Start\n\n**New to Thurup?** Follow the [Quickstart Guide](./docs/getting-started/QUICKSTART.md) to get running in 5 minutes.\n\n**Detailed setup?** See the [Installation Guide](./docs/getting-started/INSTALLATION.md).\n\n### Quick Commands\n\n**Backend:**\n```bash\ncd backend\nuv sync                                    # Install dependencies\nuv run alembic upgrade head                # Run migrations\nuv run uvicorn app.main:app --reload --port 18081\n```\n\n**Frontend:**\n```bash\ncd frontend\nnpm install                                # Install dependencies\nnpm run dev                                # Start dev server\n```\n\n**Access the app**: http://localhost:5173\n\n## 📚 Documentation\n\nComplete documentation is organized in the [`docs/`](./docs/) folder:\n\n### Getting Started\n- **[Quickstart Guide](./docs/getting-started/QUICKSTART.md)** - Get up and running in 5 minutes\n- **[Installation Guide](./docs/getting-started/INSTALLATION.md)** - Comprehensive setup instructions\n- **[Deployment Guide](./docs/getting-started/DEPLOYMENT.md)** - Production deployment strategies\n\n### Development\n- **[Developer Guide](./docs/development/DEVELOPER_GUIDE.md)** - Development workflow and best practices\n- **[Architecture](./docs/development/ARCHITECTURE.md)** - System design and structure\n- **[API Reference](./docs/development/API_REFERENCE.md)** - Complete backend API documentation\n- **[Contributing](./docs/development/CONTRIBUTING.md)** - How to contribute to the project\n\n### Testing\n- **[Testing Guide](./docs/testing/TESTING_GUIDE.md)** - Comprehensive testing documentation\n- **[Running Tests](./docs/testing/RUNNING_TESTS.md)** - Quick command reference\n\n### Planning \u0026 Implementation\n- **[Requirements](./docs/planning/REQUIREMENTS.md)** - Feature requirements and specifications\n- **[Roadmap](./docs/planning/ROADMAP.md)** - Development roadmap and milestones\n- **[Technical Debt](./docs/planning/TECHNICAL_DEBT_TODO.md)** - Known issues and improvements\n- **[Known Bugs](./docs/planning/KNOWN_BUGS.md)** - Bug tracking and status\n- **[Technical Review](./docs/planning/TECHNICAL_REVIEW.md)** - Code review and priorities\n- **[Round History Implementation](./docs/implementation/ROUND_HISTORY_IMPLEMENTATION.md)** - Game history system\n\n### Component Logs (for Claude Code)\n- **[backend/CLAUDE.md](./backend/CLAUDE.md)** - Backend development log with technical details\n- **[frontend/CLAUDE.md](./frontend/CLAUDE.md)** - Frontend development log with UI/UX changes\n\n## 🏗️ Project Structure\n\n```\nthurup/\n├── backend/              # FastAPI backend with WebSocket support\n│   ├── app/\n│   │   ├── api/v1/       # Modular API endpoints\n│   │   │   ├── router.py              # Main router and shared state\n│   │   │   ├── rest.py                # REST endpoints\n│   │   │   ├── websocket.py           # WebSocket handler\n│   │   │   ├── broadcast.py           # State broadcasting\n│   │   │   ├── bot_runner.py          # Bot AI orchestration\n│   │   │   ├── connection_manager.py  # WebSocket connections\n│   │   │   ├── persistence_integration.py  # Database integration\n│   │   │   ├── history.py             # Game history endpoints\n│   │   │   └── admin.py               # Admin endpoints\n│   │   ├── game/         # Game logic and state management\n│   │   └── db/           # Database models and persistence\n│   ├── tests/            # Unit, integration, and E2E tests\n│   └── alembic/          # Database migrations\n│\n├── frontend/             # React + TypeScript frontend\n│   ├── src/\n│   │   ├── api/          # API service layer\n│   │   ├── components/   # React components\n│   │   ├── pages/        # Page components\n│   │   ├── stores/       # Zustand state management\n│   │   └── types/        # TypeScript type definitions\n│   └── tests/e2e/        # Playwright E2E tests\n│\n├── docs/                 # Organized documentation\n│   ├── getting-started/  # Setup and installation\n│   ├── development/      # Architecture, API, contributing\n│   ├── testing/          # Testing strategies\n│   ├── planning/         # Roadmap, requirements, technical debt\n│   └── implementation/   # Feature implementation guides\n│\n└── docker-compose.yml    # Container orchestration\n```\n\n## 📊 Development Status\n\n**Backend**: ✅ Complete (331 tests, 76% coverage)\n- Core game logic and rules\n- Database persistence with SQLite + Alembic\n- REST API and WebSocket communication\n- Admin endpoints with authentication\n- Round history and replay system\n- Comprehensive testing\n\n**Frontend**: ✅ Production Ready (253 tests, 26.8% coverage)\n- ✅ Project setup and infrastructure\n- ✅ Type system and state management\n- ✅ API integration layer\n- ✅ Complete UI component library\n- ✅ Game board and gameplay UI (fully responsive)\n- ✅ Real-time WebSocket communication\n- ✅ Session persistence and recovery\n- ✅ Game history and replay viewer\n- ✅ Admin dashboard\n- ✅ E2E testing with Playwright (13 scenarios, 77% pass rate)\n\n## 🧪 Testing\n\n**Backend:**\n```bash\ncd backend\nuv run pytest                    # All tests (331 tests)\nuv run pytest tests/unit/        # Unit tests (32 tests)\nuv run pytest tests/integration/ # Integration tests (24 tests)\nuv run pytest --cov=app          # With coverage report\n```\n\n**Frontend:**\n```bash\ncd frontend\nnpm test                         # Unit/component tests (253 tests)\nnpm run test:coverage            # With coverage report\nnpm run test:e2e                 # E2E tests (requires backend running)\nnpm run test:e2e:ui              # E2E in interactive mode\n```\n\nSee [Running Tests](./docs/testing/RUNNING_TESTS.md) for more commands.\n\n## 🎯 Game Rules\n\nThurup is a trick-taking card game for 4-6 players:\n- **28 Mode**: 32 cards (7-A), 4 players, 2 teams\n- **56 Mode**: 64 cards (2 decks), 4-6 players, 2-3 teams\n- Bidding phase to determine trump suit\n- Trick-taking with trump and suit following rules\n- Points awarded based on card values and tricks won\n\nSee [Requirements](./docs/planning/REQUIREMENTS.md) for detailed game rules.\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. Review the [Architecture](./docs/development/ARCHITECTURE.md) to understand the system design\n2. Check [Contributing Guide](./docs/development/CONTRIBUTING.md) for guidelines\n3. Follow [Developer Guide](./docs/development/DEVELOPER_GUIDE.md) for setup instructions\n4. Add tests for new features\n5. Update documentation as needed\n\nSee [Contributing Guide](./docs/development/CONTRIBUTING.md) for detailed contribution guidelines.\n\n## 📝 License\n\n[Add your license here]\n\n## 🙏 Acknowledgments\n\nBuilt with modern technologies:\n- [FastAPI](https://fastapi.tiangolo.com/) - Backend framework\n- [React](https://react.dev/) - Frontend framework\n- [SQLModel](https://sqlmodel.tiangolo.com/) - Database ORM\n- [Zustand](https://zustand-demo.pmnd.rs/) - State management\n- [TailwindCSS](https://tailwindcss.com/) - Styling\n- [Playwright](https://playwright.dev/) - E2E testing\n\n---\n\n**Last Updated**: 2025-10-22\n**Status**: Production Ready\n**Version**: 0.2.0\n\n## 📋 Recent Changes\n\n### 2025-10-22: Documentation Reorganization\n- ✅ Restructured all documentation into organized subdirectories\n- ✅ Eliminated duplicate documentation (6 files merged)\n- ✅ Created comprehensive guides: Quickstart, Installation, Contributing\n- ✅ Added quick reference for running tests\n- ✅ Updated navigation with task-based \"I want to...\" guide\n- ✅ Single source of truth for all documentation topics\n\n### Week 7: Critical Bug Fixes (2025-10-15)\n- ✅ Fixed multiplayer hand visibility (WebSocket re-identification)\n- ✅ Fixed dealer rotation to follow official 28 rules\n- ✅ Improved trick card display with actual card images\n- ✅ Enhanced visual spacing and layout\n\n### Week 6: Round History Persistence (2025-10-14)\n- ✅ Implemented comprehensive round history database persistence\n- ✅ Created admin game history browser with round-by-round playback\n- ✅ Fixed player name persistence bug\n- ✅ Added \"Start Next Round\" button for multi-round gameplay\n- ✅ Enhanced admin panel with short code display\n\n### Week 5: Session Management \u0026 Visual Enhancements (2025-10-13)\n- ✅ Frontend LocalStorage persistence for player sessions\n- ✅ Modal-based join flow consistent across all entry points\n- ✅ Page refresh recovery with automatic session restoration\n- ✅ WebSocket short code resolution bug fix (critical)\n- ✅ Playing card images from Deck of Cards API\n- ✅ Responsive GameBoard layout with percentage-based positioning\n- ✅ Team-based scoring display with bid targets\n- ✅ Lead suit indicator and last trick display\n- ✅ Context-aware trump reveal feedback\n\n---\n\nFor detailed technical documentation and development logs, see:\n- [Backend Development Log](./backend/CLAUDE.md)\n- [Frontend Development Log](./frontend/CLAUDE.md)\n- [Documentation Hub](./docs/README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerynmathew%2Fthurup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjerynmathew%2Fthurup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerynmathew%2Fthurup/lists"}