{"id":41719134,"url":"https://github.com/grimm00/pokehub","last_synced_at":"2026-01-24T22:27:04.013Z","repository":{"id":314508078,"uuid":"1051363525","full_name":"grimm00/pokehub","owner":"grimm00","description":"Pokehub project","archived":false,"fork":false,"pushed_at":"2025-11-07T22:02:46.000Z","size":1754,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T22:24:07.180Z","etag":null,"topics":["backend-development","flask","jwt-authentication","learning-project","pokemon","python","rest-api","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grimm00.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-09-05T21:25:19.000Z","updated_at":"2025-10-10T18:28:49.000Z","dependencies_parsed_at":"2025-09-12T22:48:54.324Z","dependency_job_id":"940325b7-6ee0-4871-9f51-5d2560f2ff90","html_url":"https://github.com/grimm00/pokehub","commit_stats":null,"previous_names":["grimm00/pokedex","grimm00/pokehub"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/grimm00/pokehub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grimm00%2Fpokehub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grimm00%2Fpokehub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grimm00%2Fpokehub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grimm00%2Fpokehub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grimm00","download_url":"https://codeload.github.com/grimm00/pokehub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grimm00%2Fpokehub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28738815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T22:12:27.248Z","status":"ssl_error","status_checked_at":"2026-01-24T22:12:10.529Z","response_time":89,"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":["backend-development","flask","jwt-authentication","learning-project","pokemon","python","rest-api","sqlalchemy"],"created_at":"2026-01-24T22:27:03.942Z","updated_at":"2026-01-24T22:27:04.005Z","avatar_url":"https://github.com/grimm00.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pokehub - Your Pokemon Universe\n\nA modern, full-stack Pokemon database application built with React, Flask, and Docker. Features 386 Pokemon from Generations 1-3 (Kanto, Johto, Hoenn), user authentication, favorites management, generation filtering, and comprehensive testing infrastructure.\n\n## 🎯 Project Goals\n\nThis project serves as a hands-on learning experience for understanding:\n- **Backend Development**: API design, database management, data modeling\n- **Frontend Development**: Modern UI/UX, state management, responsive design\n- **DevOps Practices**: CI/CD pipelines, containerization, monitoring, deployment\n- **Full-Stack Integration**: End-to-end development workflow\n- **Documentation**: Technical writing, API documentation, deployment guides\n\n## 📁 Project Structure\n\n```\npokedex/\n├── admin/                    # Project planning and documentation\n│   ├── docs/                # Project status and maintenance docs\n│   ├── planning/            # ADRs, roadmap, and project planning\n│   │   ├── architecture/    # Architecture Decision Records (ADRs)\n│   │   ├── phases/          # Development phase documentation\n│   │   └── features/        # Feature planning and specifications\n│   ├── technical/           # Technical guides and implementation docs\n│   ├── testing/             # Testing documentation and scripts\n│   └── chat-logs/           # Development session logs (2024-2025)\n├── backend/                 # Flask REST API\n│   ├── models/              # SQLAlchemy models (Pokemon, User, Audit)\n│   ├── routes/              # API endpoints (auth, pokemon, users, cache)\n│   ├── services/            # Business logic services\n│   │   ├── cache.py         # Redis caching system\n│   │   ├── pokeapi_client.py # PokeAPI integration client\n│   │   └── security.py      # Security features and rate limiting\n│   ├── utils/               # Utility scripts and tools\n│   │   ├── pokemon_seeder.py # Data seeding logic (386 Pokemon)\n│   │   ├── generation_config.py # Generation filtering configuration\n│   │   └── validators.py    # Data validation utilities\n│   ├── migrations/          # Database migrations (Flask-Migrate)\n│   ├── instance/            # SQLite database (not in git)\n│   ├── app.py               # Main Flask application\n│   └── database.py          # Database configuration\n├── frontend/                # React TypeScript Frontend\n│   ├── src/\n│   │   ├── components/      # React components\n│   │   │   ├── pokemon/     # Pokemon-specific components\n│   │   │   │   ├── PokemonCard.tsx      # Individual Pokemon cards\n│   │   │   │   ├── PokemonModal.tsx     # Pokemon detail modals\n│   │   │   │   ├── PokemonSearch.tsx   # Search functionality\n│   │   │   │   ├── GenerationFilter.tsx # Generation filtering\n│   │   │   │   └── BulkSelection.tsx   # Bulk favorites operations\n│   │   │   └── ui/          # Reusable UI components\n│   │   ├── pages/           # Page components\n│   │   ├── services/        # API service layer\n│   │   ├── store/           # Zustand state management\n│   │   ├── types/           # TypeScript type definitions\n│   │   └── utils/           # Utility functions (sprites, etc.)\n│   ├── package.json         # Node.js dependencies\n│   └── vite.config.ts       # Vite configuration\n├── docs/                    # Documentation\n│   ├── guides/              # Technical guides\n│   │   └── docker-containerization-guide.md # Docker setup guide\n│   └── syntax/              # Code syntax documentation\n├── tests/                   # Centralized testing framework\n│   ├── unit/                # Unit tests (frontend \u0026 backend)\n│   ├── integration/         # Integration tests\n│   ├── performance/         # Performance tests\n│   ├── docker/              # Docker testing environment\n│   └── run-tests.sh         # Unified test runner (see tests/README.md)\n├── scripts/                 # Utility scripts (see scripts/README.md)\n│   ├── setup.sh             # Initial project setup\n│   ├── deploy.sh            # Deployment automation\n│   ├── health-check.sh      # Health monitoring\n│   └── test-*.sh            # Testing automation scripts\n├── requirements.txt         # Python dependencies\n├── package.json             # Root package.json for centralized scripts\n├── Dockerfile              # Multi-stage container configuration\n├── docker-compose.yml      # Multi-container setup\n├── .dockerignore           # Docker build exclusions\n└── .gitignore              # Git ignore rules\n```\n\n## ✨ Current Features\n\n### 🎮 **Pokemon Database**\n- **386 Pokemon**: Complete Generations 1-3 (Kanto, Johto, Hoenn)\n- **Generation Filtering**: Filter by Kanto, Johto, or Hoenn regions\n- **Advanced Search**: Search by name, type, and generation\n- **Pagination**: Efficient loading with \"Load More\" functionality\n- **Detailed Views**: Comprehensive Pokemon information with stats, abilities, and types\n\n### 🔐 **User Management**\n- **JWT Authentication**: Secure user registration and login\n- **Favorites System**: Add/remove Pokemon to/from favorites\n- **Bulk Operations**: Select multiple Pokemon for bulk favorites management\n- **User Profiles**: Personal dashboard and preferences\n\n### 🎨 **User Interface**\n- **Modern Design**: Clean, responsive interface with Tailwind CSS\n- **Animated Sprites**: Static and animated Pokemon sprites from PokeAPI\n- **Interactive Cards**: Hover effects and type-based color schemes\n- **Modal Details**: Detailed Pokemon information in elegant modals\n- **Skeleton Loading**: Smooth loading states and transitions\n\n### 🚀 **Performance \u0026 Reliability**\n- **Redis Caching**: 50-80% performance improvement\n- **Database Optimization**: Indexed queries and efficient pagination\n- **Health Monitoring**: Comprehensive health checks and monitoring\n- **Error Handling**: Graceful error handling and user feedback\n\n## 🚀 Getting Started\n\n### Setup Options\n\nWe provide three different ways to set up the development environment:\n\n1. **Automated Setup** (Recommended): One-command setup with automatic dependency installation\n2. **Docker Setup**: Containerized environment for consistent development\n3. **Manual Setup**: Step-by-step setup for full control\n\n### Prerequisites\n\n**Required:**\n- Python 3.9 or higher\n- Redis (for caching)\n- Git\n- Virtual environment (venv or conda)\n- **[Dev-Toolkit](https://github.com/grimm00/dev-toolkit)** - Development utilities for Git Flow, Sourcery reviews, and pre-commit hooks\n  ```bash\n  git clone https://github.com/grimm00/dev-toolkit.git ~/.dev-toolkit\n  cd ~/.dev-toolkit\n  ./install.sh\n  ```\n\n**Optional (for enhanced performance):**\n- `jq` - JSON processor for faster GitHub API operations (20x faster branch cleanup)\n  - macOS: `brew install jq`\n  - Linux: `apt-get install jq`\n  - Windows: `choco install jq`\n\n### Quick Start\n\n#### Option 1: Automated Setup (Recommended)\n```bash\ngit clone https://github.com/yourusername/pokedex.git\ncd pokedex\n./setup.sh\n```\n\n\u003e 📖 **For detailed development instructions**, see [DEVELOPMENT.md](DEVELOPMENT.md) - comprehensive guide covering setup, testing, debugging, and deployment.\n\n#### Option 2: Docker Setup\n```bash\ngit clone https://github.com/yourusername/pokedex.git\ncd pokedex\ndocker compose up --build\n```\n\n**Access the application:**\n- **Full Application**: http://localhost (Frontend + API)\n- **API Only**: http://localhost/api/v1/\n- **Health check**: http://localhost/api/v1/health\n- **API docs**: http://localhost/api/docs\n\n**Test Docker Setup:**\n```bash\n./test-docker.sh\n```\n\n#### Option 3: Manual Setup\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/yourusername/pokedex.git\n   cd pokedex\n   ```\n\n2. **Set up virtual environment**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Start Redis (for caching)**\n   ```bash\n   # macOS\n   brew install redis\n   brew services start redis\n   \n   # Ubuntu/Debian\n   sudo apt-get install redis-server\n   sudo systemctl start redis\n   \n   # Verify Redis is running\n   redis-cli ping\n   ```\n\n5. **Set up environment variables**\n   ```bash\n   cp env.example .env\n   # Edit .env with your configuration\n   ```\n\n5. **Initialize database**\n   ```bash\n   python -m flask db upgrade\n   python -m backend.seed_pokemon seed-range 1 20\n   ```\n\n6. **Run the application**\n   ```bash\n   python -m backend.app\n   ```\n\n7. **Test the API**\n   ```bash\n   curl http://localhost:5000/api/v1/pokemon\n   ```\n\n### Frontend Setup (React + TypeScript)\n\n1. **Navigate to frontend directory**\n   ```bash\n   cd frontend\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Start the development server**\n   ```bash\n   npm run dev\n   ```\n\n4. **Access the application**\n   - Frontend: http://localhost:3001 (or 3000 if available)\n   - Backend API: http://localhost:5000\n\n### Full-Stack Development\n\nTo run both frontend and backend together:\n\n1. **Terminal 1 - Backend**\n   ```bash\n   export DATABASE_URL=\"sqlite:///$(pwd)/instance/pokedex_dev.db\"\n   python3 -m backend.app\n   ```\n\n2. **Terminal 2 - Frontend**\n   ```bash\n   cd frontend\n   npm run dev\n   ```\n\n3. **Access the application**\n   - Open http://localhost:3001 in your browser\n   - The frontend will automatically connect to the backend API\n\n## 🌳 Development Workflow\n\nWe use **Git Flow** for organized development:\n\n```\nmain (production) ← develop (integration) ← feat/* (features)\n```\n\n**Quick Start:**\n```bash\n# Start new feature\n./scripts/workflow-helper.sh start-feature my-feature\n\n# Check status  \n./scripts/workflow-helper.sh status\n```\n\n\u003e 📖 **For detailed workflow and contributing guidelines**, see [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### 🛠️ Dev-Toolkit Commands\n\nThis project uses [dev-toolkit](https://github.com/grimm00/dev-toolkit) for development utilities:\n\n**Git Flow Safety:**\n```bash\ndt-git-safety check          # Run all safety checks\ndt-git-safety branch         # Check current branch\ndt-git-safety conflicts      # Check for merge conflicts\ndt-install-hooks             # Install pre-commit hooks\n```\n\n**Sourcery Code Reviews:**\n```bash\ndt-review 42                 # Extract Sourcery review for PR #42\n                            # Saves to admin/feedback/sourcery/pr42.md\n```\n\n**Configuration:**\n```bash\ndt-config show              # View current config\ndt-config create global     # Create global config\ndt-config create project    # Create project config (.dev-toolkit.conf)\n```\n\n**Pre-commit Hooks:**\n- Automatically installed via `dt-install-hooks`\n- Checks branch safety (prevents commits to protected branches)\n- Detects potential merge conflicts\n- Prevents committing sensitive files (.env, .key, etc.)\n- Warns about large files (\u003e10MB)\n\n\u003e 💡 **Tip:** Run `dt-install-hooks` after cloning to enable automatic safety checks!\n\n## 🔌 API Endpoints\n\n### Pokemon Endpoints\n- `GET /api/v1/pokemon` - List all Pokemon (with pagination, search, filtering)\n- `GET /api/v1/pokemon/{id}` - Get specific Pokemon details\n- `GET /api/v1/pokemon?type=fire` - Filter by type\n- `GET /api/v1/pokemon?search=char` - Search by name\n- `GET /api/v1/pokemon?generation=2` - Filter by generation (1=Kanto, 2=Johto, 3=Hoenn)\n- `GET /api/v1/pokemon/generations` - Get all available generations\n\n### Authentication Endpoints\n- `POST /api/v1/auth/register` - User registration\n- `POST /api/v1/auth/login` - User login\n- `POST /api/v1/auth/refresh` - Refresh JWT token\n- `POST /api/v1/auth/logout` - User logout\n\n### User Endpoints\n- `GET /api/v1/users/profile` - Get user profile\n- `PUT /api/v1/users/profile` - Update user profile\n- `GET /api/v1/users/favorites` - Get user's favorite Pokemon\n- `POST /api/v1/users/favorites/{pokemon_id}` - Add Pokemon to favorites\n- `DELETE /api/v1/users/favorites/{pokemon_id}` - Remove Pokemon from favorites\n\n### Cache Management Endpoints\n- `GET /api/v1/cache/stats` - Redis cache statistics\n- `GET /api/v1/cache/health` - Cache health check\n- `DELETE /api/v1/cache/clear` - Clear all cache data\n- `DELETE /api/v1/cache/pokemon/clear` - Clear Pokemon cache only\n\n### Health Check\n- `GET /` - API health status and version info (includes cache status)\n\n## 📋 Development Phases\n\n### Phase 1: Foundation \u0026 Planning ✅\n- [x] Project architecture design\n- [x] Technology stack selection\n- [x] Development roadmap creation\n- [x] Development environment setup\n- [x] Git workflow establishment\n\n### Phase 2: Backend Development ✅\n- [x] Database design and setup (SQLite with migrations)\n- [x] API development (Flask-RESTful with JWT auth)\n- [x] External API integration (PokeAPI with 386 Pokemon - Generations 1-3)\n- [x] Backend testing (40/40 tests passing - 100% coverage)\n- [x] Security implementation (rate limiting, validation, audit logging)\n- [x] Performance optimization (database indexes, query optimization)\n- [x] Redis caching implementation (50-80% performance improvement)\n\n### Phase 3: Frontend Development ✅\n- [x] UI/UX design with modern React components\n- [x] Component development (PokemonCard, PokemonModal, PokemonSearch, GenerationFilter, BulkSelection)\n- [x] State management with Zustand\n- [x] Frontend testing (69/70 tests passing - 98.6% coverage)\n- [x] Responsive design with Tailwind CSS\n- [x] User authentication and favorites management\n\n### Phase 4: Testing \u0026 Quality Assurance ✅\n- [x] Comprehensive testing framework setup\n- [x] Docker testing environment (100% backend, 98.6% frontend)\n- [x] Integration testing with real data\n- [x] Performance testing and optimization\n- [x] Cross-browser compatibility testing\n\n### Phase 5: DevOps \u0026 CI/CD (In Progress)\n- [x] Containerization with Docker\n- [x] Project structure cleanup and organization\n- [ ] CI/CD pipeline setup with GitHub Actions\n- [ ] Automated testing and deployment\n- [ ] Production deployment and monitoring\n\n### Phase 6: Production \u0026 Monitoring (Planned)\n- [ ] Cloud deployment\n- [ ] Monitoring and alerting setup\n- [ ] Performance monitoring\n- [ ] Documentation completion\n\n## 🛠️ Technology Stack\n\n### Backend\n- **Language**: Python 3.13+\n- **Framework**: Flask with Flask-RESTful\n- **Database**: SQLite (development) / PostgreSQL (production)\n- **ORM**: SQLAlchemy with Flask-Migrate\n- **Authentication**: JWT with Flask-JWT-Extended\n- **Security**: Flask-Limiter, bcrypt, comprehensive input validation\n- **Testing**: pytest with Flask-Testing (40/40 tests passing)\n- **Caching**: Redis for performance optimization\n\n### Frontend\n- **Language**: TypeScript\n- **Framework**: React 18 with Vite\n- **State Management**: Zustand\n- **Styling**: Tailwind CSS\n- **Testing**: Vitest with React Testing Library (69/70 tests passing)\n- **Build Tool**: Vite for fast development and building\n\n### DevOps \u0026 Testing\n- **Containerization**: Docker with multi-stage builds\n- **Testing**: Comprehensive test suite (109/110 tests passing)\n- **CI/CD**: GitHub Actions (planned)\n- **Monitoring**: Health checks and performance monitoring\n\n### External Integrations\n- **PokeAPI**: Real Pokemon data integration (386 Pokemon - Generations 1-3)\n- **Data Seeding**: Custom CLI tools for data management\n\n### Development Tools\n- **Version Control**: Git with feature branch workflow\n- **Documentation**: Markdown with comprehensive project docs\n- **Code Quality**: ESLint, Prettier, comprehensive .gitignore\n\n## 📚 Learning Resources\n\n### **Project Documentation**\n- [Project Brainstorming](./admin/docs/planning-notes/brainstorming.md) - Initial ideas and technical considerations\n- [Development Roadmap](./admin/docs/roadmap.md) - Detailed 10-week development plan\n- [Development Rules](./admin/docs/rules.md) - Project guidelines and best practices\n\n### **Frontend Learning**\n- [Frontend Design Document](./admin/docs/features/frontend-design.md) - Complete UI/UX design and technology deep dive\n- **Vite** - Ultra-fast build tool and development server\n- **Zustand** - Lightweight state management (2.9kb)\n- **Tailwind CSS** - Utility-first CSS framework\n- **Headless UI** - Accessible, unstyled React components\n\n### **Backend Learning**\n- [ADR-001: Technology Stack](./admin/docs/architecture/adrs/adr-001-technology-stack.md) - Backend technology decisions\n- [ADR-002: Database Design](./admin/docs/architecture/adrs/adr-002-database-design.md) - Database schema and patterns\n- [ADR-003: API Design](./admin/docs/architecture/adrs/adr-003-api-design-patterns.md) - RESTful API patterns\n- [ADR-004: Security](./admin/docs/architecture/adrs/adr-004-security-implementation.md) - Security implementation\n- [ADR-005: PokeAPI Integration](./admin/docs/architecture/adrs/adr-005-pokeapi-integration-strategy.md) - PokeAPI integration strategy\n- [ADR-006: Deployment Strategy](./admin/docs/architecture/adrs/adr-006-deployment-strategy.md) - Deployment and CI/CD strategy\n## 🤝 Contributing\n\nContributions are welcome! This is a learning project focused on full-stack development best practices.\n\n**Quick Start:**\n1. Fork the repository\n2. Use our Git Flow: `./scripts/git-flow-helper.sh start-feature your-feature`\n3. Make changes and test thoroughly\n4. Create PR to `develop` branch\n\n\u003e 📖 **For detailed guidelines, workflow, and setup**, see [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## 📝 License\n\nThis project is for educational purposes. Pokemon data and images are property of Nintendo/Game Freak.\n\n## 🎓 Learning Objectives\n\nBy the end of this project, you should have:\n- [ ] Complete understanding of chosen technology stack\n- [ ] Ability to deploy and maintain production systems\n- [ ] Experience with CI/CD best practices\n- [ ] Knowledge of monitoring and debugging\n- [ ] Portfolio-ready project demonstrating full-stack skills\n\n---\n\n## 👨‍💻 Author\n\n**grimm00** - [GitHub](https://github.com/grimm00)\n\n*This project is part of a DevOps apprenticeship program focused on learning the complete development lifecycle.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrimm00%2Fpokehub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrimm00%2Fpokehub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrimm00%2Fpokehub/lists"}