🔄 Refactor documentation to update the restructuring plan for Pokedex.Online

2026-01-28 22:08:27 +00:00
parent 649c7733c3
commit ed44fad9bd
1 changed files with 315 additions and 0 deletions
--- a/docs/projects/Pokedex.Online/REFACTORING-PLAN.md
+++ 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)