diff --git a/docs/projects/Pokedex.Online/REFACTORING-PLAN.md b/docs/projects/Pokedex.Online/REFACTORING-PLAN.md new file mode 100644 index 0000000..cdf626b --- /dev/null +++ b/docs/projects/Pokedex.Online/REFACTORING-PLAN.md @@ -0,0 +1,315 @@ +# Pokedex.Online - Comprehensive Refactoring & Enhancement Plan + +**Status**: In Progress +**Start Date**: January 28, 2026 +**Estimated Duration**: 8-12 weeks + +## Overview + +This document outlines the complete refactoring plan for Pokedex.Online, transforming it from a prototype into a production-ready application with proper testing, monitoring, CI/CD, and scalable architecture. + +## Goals + +1. **Code Quality**: Reduce component complexity (GamemasterExplorer: 1627→400 lines, ChallongeTest: 1832→500 lines) +2. **Testing**: Achieve 85%+ code coverage with Vitest +3. **Security**: Implement JWT authentication and secure feature flags +4. **Production Ready**: Multi-container Docker deployment with health checks +5. **Monitoring**: Error tracking and performance monitoring with Sentry +6. **CI/CD**: Automated testing and deployment with Gitea Actions +7. **Performance**: Bundle optimization, accessibility, mobile-first +8. **Maintainability**: Organized documentation structure +9. **Future-Ready**: Architecture prepared for database, i18n, scaling + +## Documentation Structure + +``` +/docs/projects/Pokedex.Online/ +├── REFACTORING-PLAN.md (this file) +├── setup/ +│ ├── gamemaster-setup.md +│ ├── deployment.md +│ ├── monitoring.md +│ ├── gitea-cicd.md +│ ├── security.md +│ └── accessibility.md +├── api-reference/ +│ ├── oauth-setup.md +│ ├── gamemaster-api.md +│ └── authentication.md +├── architecture/ +│ ├── authentication.md +│ ├── internationalization.md +│ ├── feature-flags.md +│ └── deployment-architecture.md +├── roadmap/ +│ └── gamemaster-explorer-future.md +└── archive/ + ├── implementation-notes.md + └── cleanup.md +``` + +## Phase Breakdown + +### Phase 1: Documentation & Project Setup ✅ +**Duration**: 1-2 days +**Status**: In Progress + +1. Create documentation folder structure (✅ DONE) +2. Move existing documentation to organized locations +3. Set up Vitest testing infrastructure +4. Split package.json dependencies (frontend/backend separation) + +### Phase 2: Shared Utilities & Patterns +**Duration**: 3-4 days +**Status**: Not Started + +1. Create `composables/useAsyncState.js` - Standardized async operations +2. Create `utilities/api-client.js` - Centralized fetch wrapper +3. Create `components/shared/BaseButton.vue` - Reusable button component +4. Create `components/shared/BaseModal.vue` - Reusable modal component +5. Update all components to use shared utilities + +### Phase 3: Authentication System +**Duration**: 4-5 days +**Status**: Not Started + +1. Design JWT authentication architecture +2. Implement backend JWT auth (login, refresh, verify endpoints) +3. Implement frontend auth composable and login UI +4. Document authentication system for future reference + +### Phase 4: Feature Flags with Authentication +**Duration**: 2-3 days +**Status**: Not Started + +1. Create secure feature flag system with obfuscation +2. Add developer tools panel (Ctrl+Shift+D) +3. Integrate feature flags in views and router +4. Write tests for feature flag system + +### Phase 5: GamemasterExplorer Refactoring +**Duration**: 5-7 days +**Status**: Not Started + +1. Extract `useGamemasterSearch.js` composable +2. Extract `useGamemasterFiles.js` composable +3. Extract `useLineSelection.js` composable +4. Extract `useJsonFilter.js` composable +5. Create `SearchBar.vue` component +6. Create `FileSelector.vue` component +7. Create `JsonViewer.vue` component +8. Create `ActionToolbar.vue` component +9. Refactor main component (1627 → ~400 lines) + +**Target Reduction**: 1627 lines → 400 lines (76% reduction) + +### Phase 6: ChallongeTest Refactoring +**Duration**: 4-5 days +**Status**: Not Started + +1. Extract `useChallongeClient.js` composable +2. Extract `useChallongeTests.js` composable +3. Create `ApiVersionSelector.vue` component +4. Create `TournamentGrid.vue` component +5. Create `TournamentDetail.vue` component +6. Refactor main component (1832 → ~500 lines) + +**Target Reduction**: 1832 lines → 500 lines (73% reduction) + +### Phase 7: Production Deployment +**Duration**: 3-4 days +**Status**: Not Started + +1. Create multi-container Docker setup (frontend + backend) +2. Update Nginx configuration for production +3. Prepare backend servers for production +4. Update build scripts +5. Update deployment automation +6. Test production deployment locally + +### Phase 8: Backend Improvements +**Duration**: 5-6 days +**Status**: Not Started + +1. Add structured logging with Winston +2. Add rate limiting middleware +3. Implement gamemaster file caching with TTL +4. Add comprehensive error handling +5. Add health check endpoints +6. Add API input validation +7. Write comprehensive backend tests + +### Phase 9: Application Monitoring +**Duration**: 2-3 days +**Status**: Not Started + +1. Set up error tracking with Sentry (frontend + backend) +2. Add performance monitoring +3. Configure monitoring dashboards and alerts +4. Add source maps for production debugging +5. Test monitoring integration + +### Phase 10: CI/CD Pipeline with Gitea +**Duration**: 4-5 days +**Status**: Not Started + +1. Set up Gitea repository and runner +2. Create test workflow +3. Create build workflow +4. Create staging deployment workflow +5. Create production deployment workflow +6. Document CI/CD processes + +### Phase 11: Security, Performance, Accessibility +**Duration**: 5-7 days +**Status**: Not Started + +1. Security audit and hardening +2. Frontend performance optimization +3. Backend performance optimization +4. Accessibility audit and fixes +5. Mobile optimization +6. i18n preparation +7. Add performance budgets to CI +8. Documentation review and update + +### Phase 12: Final Testing & Validation +**Duration**: 3-4 days +**Status**: Not Started + +1. Run complete test suite (target 85%+ coverage) +2. Manual testing checklist (all features, error scenarios, browsers) +3. Docker deployment validation +4. CI/CD pipeline validation +5. Monitoring validation +6. Final documentation review + +## Timeline Estimate + +| Phase | Duration | Cumulative | +|-------|----------|------------| +| Phase 1: Documentation & Setup | 2 days | 2 days | +| Phase 2: Shared Utilities | 4 days | 6 days | +| Phase 3: Authentication | 5 days | 11 days | +| Phase 4: Feature Flags | 3 days | 14 days | +| Phase 5: GamemasterExplorer | 7 days | 21 days | +| Phase 6: ChallongeTest | 5 days | 26 days | +| Phase 7: Deployment | 4 days | 30 days | +| Phase 8: Backend | 6 days | 36 days | +| Phase 9: Monitoring | 3 days | 39 days | +| Phase 10: CI/CD | 5 days | 44 days | +| Phase 11: Performance & A11y | 7 days | 51 days | +| Phase 12: Final Testing | 4 days | **55 days** | + +**Total Estimated Duration**: 55 working days (~11 weeks) + +## Success Metrics + +- [ ] Code coverage ≥85% +- [ ] Bundle size ≤250kb (main JS) +- [ ] Lighthouse Performance ≥90 +- [ ] Lighthouse Accessibility ≥95 +- [ ] Page load time ≤2s +- [ ] API response time P95 ≤200ms +- [ ] Error rate ≤0.1% +- [ ] Zero-downtime deployments +- [ ] All tests passing in CI/CD + +## Key Technical Decisions + +### Testing Framework +- **Choice**: Vitest +- **Rationale**: Fast, native ESM support, compatible with Vite, excellent Vue support + +### Authentication +- **Choice**: JWT with httpOnly cookies +- **Rationale**: Stateless, scalable, secure against XSS when using httpOnly cookies + +### Monitoring +- **Choice**: Sentry +- **Rationale**: Excellent error tracking, performance monitoring, source map support, affordable + +### CI/CD Platform +- **Choice**: Gitea Actions +- **Rationale**: Self-hosted, familiar GitHub Actions syntax, privacy control + +### Container Strategy +- **Choice**: Multi-container (frontend + backend) +- **Rationale**: Independent scaling, clearer separation of concerns, easier debugging + +### Caching Strategy +- **Choice**: In-memory with TTL (now), Redis-ready (future) +- **Rationale**: Simple for single instance, easy migration path to Redis + +### Feature Flags +- **Choice**: Code-based with build-time obfuscation +- **Rationale**: No external service needed, secure, controlled rollout + +## Dependencies to Add + +### Frontend +```json +{ + "vitest": "^1.2.0", + "@vitest/ui": "^1.2.0", + "@vitest/coverage-v8": "^1.2.0", + "@vue/test-utils": "^2.4.3", + "jsdom": "^23.2.0", + "happy-dom": "^12.10.3", + "@sentry/vue": "^7.99.0", + "@sentry/vite-plugin": "^2.14.0" +} +``` + +### Backend +```json +{ + "express-rate-limit": "^7.1.5", + "winston": "^3.11.0", + "winston-daily-rotate-file": "^4.7.1", + "jsonwebtoken": "^9.0.2", + "bcrypt": "^5.1.1", + "joi": "^17.12.0", + "@sentry/node": "^7.99.0", + "@sentry/profiling-node": "^1.3.3" +} +``` + +## Risks & Mitigation + +| Risk | Impact | Mitigation | +|------|--------|------------| +| Breaking existing features during refactor | High | Comprehensive tests before refactoring, integration tests | +| Authentication complexity | Medium | Clear documentation, JWT library handles complexity | +| Docker deployment issues | Medium | Thorough local testing before production deploy | +| Performance regression | Medium | Performance budgets in CI, monitoring dashboards | +| Over-engineering | Low | Follow plan, don't add features not in scope | + +## Future Enhancements (Post-Refactor) + +1. **Database Integration** - PostgreSQL for Tournament Manager +2. **Redis Caching** - For multi-instance scaling +3. **Printing Tool** - Tournament materials generation +4. **Tournament Manager** - Full CRUD for tournaments +5. **Advanced Search** - Regex, bookmarks, diff viewer for gamemaster +6. **User Accounts** - If expanding beyond personal use +7. **Internationalization** - Multi-language support +8. **PWA Features** - Offline support, installability +9. **Advanced Analytics** - Usage tracking, feature adoption +10. **API Rate Limiting Dashboard** - Visual quota management + +## Notes + +- All phases build on previous phases - follow order +- Write tests alongside each refactor, not after +- Update documentation as you go +- Run full test suite before merging phases +- Keep production deployment working throughout refactor +- Use feature flags to hide incomplete features + +## References + +- [Original README](../../code/websites/pokedex.online/README.md) +- [OAuth Setup](api-reference/oauth-setup.md) +- [Gamemaster API](api-reference/gamemaster-api.md) +- [Future Features Roadmap](roadmap/gamemaster-explorer-future.md)