{"id":37315409,"url":"https://github.com/gitayam/debate-bingo","last_synced_at":"2026-01-16T03:08:57.603Z","repository":{"id":256500972,"uuid":"855489631","full_name":"gitayam/debate-bingo","owner":"gitayam","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-19T04:00:10.000Z","size":299,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-19T06:03:35.209Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gitayam.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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-11T00:29:50.000Z","updated_at":"2025-11-19T04:00:13.000Z","dependencies_parsed_at":"2024-09-11T05:50:38.698Z","dependency_job_id":"5570e8cc-9d3b-4157-b9b8-5226dc79d129","html_url":"https://github.com/gitayam/debate-bingo","commit_stats":null,"previous_names":["gitayam/debate-bingo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gitayam/debate-bingo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitayam%2Fdebate-bingo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitayam%2Fdebate-bingo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitayam%2Fdebate-bingo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitayam%2Fdebate-bingo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitayam","download_url":"https://codeload.github.com/gitayam/debate-bingo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitayam%2Fdebate-bingo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28476877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:02:43.018Z","status":"ssl_error","status_checked_at":"2026-01-16T03:01:27.857Z","response_time":107,"last_error":"SSL_read: 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":[],"created_at":"2026-01-16T03:08:57.012Z","updated_at":"2026-01-16T03:08:57.590Z","avatar_url":"https://github.com/gitayam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Debate Bingo\n\nA modern, interactive debate bingo application built with **Next.js 15**, **FastAPI**, and **PostgreSQL**. Originally inspired by a simple Streamlit app, this version provides a production-ready, scalable solution with real-time game state management.\n\n## 🎯 Features\n\n- **Interactive Bingo Cards**: 3×3 and 5×5 grid options\n- **Real-time Updates**: Game state synchronized across sessions\n- **Persistent Storage**: PostgreSQL database for game history\n- **Modern UI**: Responsive design with dark mode support\n- **Type Safety**: Full TypeScript implementation\n- **RESTful API**: FastAPI backend with automatic OpenAPI documentation\n- **Development Ready**: Docker setup for easy development\n\n## 🏗️ Architecture\n\n### Backend (FastAPI)\n- **FastAPI** - Modern Python web framework\n- **SQLAlchemy** - Database ORM with migrations\n- **Pydantic** - Data validation and serialization\n- **PostgreSQL** - Primary database\n- **Redis** - Session management and caching\n- **Alembic** - Database migration management\n\n### Frontend (Next.js 15)\n- **Next.js 15** - React framework with App Router\n- **TypeScript** - Type safety throughout\n- **Tailwind CSS v4** - Utility-first styling\n- **Zustand** - Lightweight state management\n- **TanStack Query** - Server state management\n- **Responsive Design** - Mobile-first approach\n\n## 🚀 Quick Start\n\n### Prerequisites\n- **Docker \u0026 Docker Compose** (recommended)\n- **Node.js 18+** and **Python 3.11+** (for local development)\n\n### Option 1: Docker (Recommended)\n\n1. **Clone and setup:**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd debate-bingo\n   ./scripts/dev-setup.sh\n   ```\n\n2. **Start all services:**\n   ```bash\n   docker-compose up\n   ```\n\n3. **Access the application:**\n   - Frontend: http://localhost:3745\n   - Backend API: http://localhost:8745\n   - API Documentation: http://localhost:8745/docs\n\n### Option 2: Local Development\n\n1. **Setup infrastructure:**\n   ```bash\n   docker-compose up -d postgres redis\n   ```\n\n2. **Backend setup:**\n   ```bash\n   cd backend\n   pip install poetry\n   poetry install\n   poetry run alembic upgrade head\n   poetry run python app/utils/init_db.py\n   poetry run uvicorn app.main:app --reload --port 8745\n   ```\n\n3. **Frontend setup:**\n   ```bash\n   cd frontend\n   npm install\n   npm run dev\n   ```\n\n## 🎮 How to Play\n\n1. **Start a New Game**: Choose your player name and grid size (3×3 or 5×5)\n2. **Watch the Debate**: Click phrases when they occur during the debate\n3. **Get BINGO**: Complete a row, column, or diagonal to win\n4. **Track Progress**: View your timeline and game statistics\n\n## 📁 Project Structure\n\n```\ndebate-bingo/\n├── backend/                 # FastAPI backend\n│   ├── app/\n│   │   ├── api/            # API routes\n│   │   ├── core/           # Configuration\n│   │   ├── models/         # SQLAlchemy models\n│   │   ├── schemas/        # Pydantic schemas\n│   │   ├── services/       # Business logic\n│   │   └── utils/          # Utilities\n│   ├── tests/              # Backend tests\n│   ├── alembic/            # Database migrations\n│   └── pyproject.toml      # Python dependencies\n├── frontend/               # Next.js frontend\n│   ├── src/\n│   │   ├── app/            # Next.js App Router\n│   │   ├── components/     # React components\n│   │   ├── hooks/          # Custom hooks\n│   │   ├── services/       # API services\n│   │   ├── stores/         # Zustand stores\n│   │   └── types/          # TypeScript types\n│   └── package.json        # Node.js dependencies\n├── scripts/                # Development scripts\n├── docs/                   # Documentation\n└── docker-compose.yml      # Docker services\n```\n\n## 🛠️ Development\n\n### Backend Commands\n```bash\ncd backend\n\n# Install dependencies\npoetry install\n\n# Run development server\npoetry run uvicorn app.main:app --reload --port 8745\n\n# Database migrations\npoetry run alembic revision --autogenerate -m \"Description\"\npoetry run alembic upgrade head\n\n# Run tests\npoetry run pytest\n\n# Linting and formatting\npoetry run black .\npoetry run flake8 .\npoetry run mypy .\n```\n\n### Frontend Commands\n```bash\ncd frontend\n\n# Install dependencies\nnpm install\n\n# Run development server\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Run tests\nnpm test\n\n# Linting and type checking\nnpm run lint\nnpm run type-check\n```\n\n## 🗄️ Database Schema\n\n### Core Tables\n- **bingo_phrases** - All available bingo phrases\n- **bingo_game_sessions** - Individual game instances\n- **bingo_cards** - Card positions and states\n\n### Key Features\n- **Automatic timestamps** on all models\n- **Foreign key relationships** for data integrity\n- **Database migrations** with Alembic\n- **Sample data initialization** with debate phrases\n\n## 🔧 Configuration\n\n### Environment Variables\n\n**Backend** (`.env`):\n```env\nDATABASE_URL=postgresql://postgres:password@localhost:5432/debate_bingo_dev\nREDIS_URL=redis://localhost:6379/0\nSECRET_KEY=your-secret-key-here\nALLOWED_ORIGINS=[\"http://localhost:3745\"]\n```\n\n**Frontend** (`.env.local`):\n```env\nNEXT_PUBLIC_API_URL=http://localhost:8745\n```\n\n## 📊 API Documentation\n\nThe FastAPI backend automatically generates interactive API documentation:\n- **Swagger UI**: http://localhost:8745/docs\n- **ReDoc**: http://localhost:8745/redoc\n\n### Key Endpoints\n- `GET /api/v1/bingo/phrases` - Get all bingo phrases\n- `POST /api/v1/bingo/game` - Create new game session\n- `GET /api/v1/bingo/game/{session_id}` - Get game state\n- `PATCH /api/v1/bingo/game/{session_id}/position/{position}` - Update card\n\n## 🧪 Testing\n\n### Backend Testing\n```bash\ncd backend\npoetry run pytest                    # Run all tests\npoetry run pytest --cov             # With coverage\npoetry run pytest tests/unit/       # Unit tests only\n```\n\n### Frontend Testing\n```bash\ncd frontend\nnpm test                            # Run all tests\nnpm run test:coverage               # With coverage\nnpm run test:ui                     # Interactive UI\n```\n\n## 🚢 Deployment\n\n### Production Build\n```bash\n# Backend\ncd backend\npoetry export -f requirements.txt --output requirements.txt\ndocker build -f Dockerfile.prod -t debate-bingo-backend .\n\n# Frontend\ncd frontend\nnpm run build\ndocker build -f Dockerfile.prod -t debate-bingo-frontend .\n```\n\n### Environment Setup\n- Configure production database and Redis\n- Set secure `SECRET_KEY` and proper CORS origins\n- Use environment-specific configuration files\n\n## 🎨 Design System\n\n### Colors\n- **Primary**: Orange (#ED6C1A) - Main brand color\n- **Gray Scale**: Tailwind's gray palette for UI elements\n- **Status Colors**: Green (success), Red (error), Yellow (warning)\n\n### Typography\n- **Sans Serif**: Inter (body text, UI)\n- **Display**: Playfair Display (headings, logo)\n\n### Components\n- **Cards**: Rounded corners with subtle shadows\n- **Buttons**: Primary/secondary variants with hover states\n- **Grid**: Responsive bingo grid with click animations\n\n## 🤝 Contributing\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Code Standards\n- **Backend**: Black formatting, flake8 linting, mypy type checking\n- **Frontend**: ESLint, Prettier, TypeScript strict mode\n- **Commits**: Conventional commit messages\n- **Tests**: Required for new features\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Original Streamlit implementation inspiration\n- Political debate entertainment community\n- Open source contributors\n\n---\n\n**Built with ❤️ for political debate entertainment**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitayam%2Fdebate-bingo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitayam%2Fdebate-bingo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitayam%2Fdebate-bingo/lists"}