memory-infrastructure-palace/docs/projects/Pokedex.Online/REFACTORING-PLAN.md

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

{
  "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

{
  "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
• OAuth Setup
• Gamemaster API
• Future Features Roadmap