2025-12-07
- Добавлена подробная инструкция по миграции в Coolify (Docker backend, статический web/admin, внешняя БД) — `docs/coolify-migration.md`.
# Mnemo Cards Project Progress

## Infrastructure & Deployment

### ✅ Completed Tasks

- **nginx Configuration System**: Implemented robust nginx configuration generation and deployment
  - Created `generate-nginx-configs.sh` for generating all nginx configurations
  - Created `deploy-nginx-configs.sh` for safe deployment with validation
  - Updated `check-nginx.sh` with port conflict detection and cleanup
  - Integrated into CI/CD pipeline

- **Reverse Proxy Architecture**: Properly configured nginx as reverse proxy for all services
  - `mnemo-cards.online` → Flutter web app (static files)
  - `code.mnemo-cards.online` → Forgejo (port 3000)
  - `vscode.mnemo-cards.online` → VSCode Server (port 8443)

- **Automated Version Management**: Implemented pre-deploy version bumping
  - Created `bump-version.sh` script for automatic version increment
  - Integrated as pre-hook in CI/CD pipeline
  - Updates both pubspec.yaml and API configuration
  - Automatic git commit with version changes

- **SSL/TLS Configuration**: Secure HTTPS setup with Let's Encrypt certificates
  - Multi-domain certificates for all subdomains
  - Proper certificate permissions and renewal

- **Admin API Configuration**: Fixed admin authentication routing
  - Admin panel now correctly routes authentication requests to production backend
  - Prevents localhost:8000 routing issues during development
  - Separate API client for admin endpoints ensures proper server targeting

- **Admin Cards: Voice Upload on Save**: Fixed voice upload when updating/creating cards in admin
  - Added "Voice (will be added on Save)" to card editor and upload on Create/Update
  - Ensured voices list still loads while the form is disabled during save
  - Added unit tests for the upsert+voice flow (`mnemo_cards_admin`)
- **Admin Packs: Color Palette Picker**: Added palette-based color selection for packs
  - Replaced free-text color input with swatches + native color picker
  - Added unit tests for the new color picker component (`mnemo_cards_admin`)
- **Admin Tests: Pack Linking**: Added ability to link tests to packs in admin
  - Test editor now supports selecting packs and syncing links on Save
  - Added unit test coverage for the new pack-linking component (`mnemo_cards_admin`)

- **Service Reliability**: Enhanced service management and monitoring
  - Port conflict detection and resolution
  - Orphaned process cleanup
  - Configuration validation before deployment
  - Emergency fallback configurations
  - Coolify container orchestration platform deployed

### 🔄 In Progress

- **Coolify Migration**: Container orchestration platform for services
  - Coolify installed and configured on `coolify.mnemo-cards.online`
  - Automatic startup configured via cron @reboot
  - Ready for service migration (backend, web, admin)
- **Monitoring & Alerting**: Implement comprehensive service monitoring
- **Backup Automation**: Automated backup procedures for all services

### 📋 Planned Tasks

- **Load Balancing**: Implement load balancing for high availability
- **CDN Integration**: Content delivery network for static assets
- **Security Hardening**: Additional security measures and hardening

## Development Status

### Web Application (mnemo_cards_web_v2)
- **Framework**: Flutter Web
- **Status**: Active development
- **Key Features**: Vocabulary learning, testing, statistics
- **Recent Updates**:
  - Added card voice support (metadata, API, web playback with error UI)
    - New voices collection linked to cards and protected endpoints for list/mp3 (Bearer)
    - Web playback: download bytes via authenticated API and play from memory (fixes 401 on `<audio src>` without headers)
    - Added unit tests for voice metadata fetching and voice-bytes download
  - Card UI: moved voice play icon into a `Stack` overlay so it doesn't take an extra row on the card (with widget test coverage)
  - CardViewer UI: navigation arrows are now constrained under the card on wide screens; favorites (heart) button is positioned closer to the card
    - Added widget test coverage for wide-screen navigation button positioning
  - Added app version display on authentication page
  - **UI Components Refactoring**: Extracted authentication components
    - Created `SignInWithGoogleButton` component for Google authentication
    - Created `SignInWithTelegram` component for Telegram authentication
    - Improved code maintainability and reusability
  - **Profile Page UI/UX Improvements**: Enhanced profile page design and functionality
    - Removed guest view - profile now only accessible for authenticated users
    - Removed account statistics (packs/purchases) from profile
    - Removed language toggle from settings
    - Created custom `ThemeToggleWidget` with sun/moon icons and animations
    - Enhanced subscription section with premium badge and upgrade button for free users
    - Added staggered animations for card appearances
    - Improved logout flow with confirmation dialog
    - Added comprehensive unit tests for new components
- **Game/Test Flow Cleanup**: Simplified testing UX and fixed theme visuals
  - Removed legacy traditional test entry from `test_page.dart` (interactive mode only)
  - Added SafeArea wrapping and themed question cards on `game_page.dart`
  - Added widget tests for themed question cards, exit control, and interactive-only notice
  - Timer/progress now sourced from live session state on `game_page.dart`
- **Game Tests Package**: Started shared package `games/packages/game_tests`
  - Added configurable `GameTestSettings` (sounds/haptics/delay)
  - Integrated into `mnemo_cards_web_v2` via `TestsModule`/`TestsStateManager`
  - **Test Page Code Quality Fix**: Fixed critical code duplication and compilation issues
    - Removed 700+ lines of duplicate code in `test_page.dart`
    - Added missing state variables for test functionality
    - Created `TestResult` class for proper result handling
    - Fixed deprecated `withOpacity` method calls
    - Restored full test functionality with interactive game and traditional test modes
  - **PackDetailsHeader Code Fix**: Fixed critical structural issues in pack details header widget
    - Resolved broken method structure with hanging code blocks
    - Created missing `_buildTitleSection` method
    - Removed undefined `cachedImage` variable usage
    - Cleaned up unused imports
    - Fixed all linter errors and compilation issues
  - **Matrix Test (image selection)**: Added new multi-stage matrix question type (one screen)
    - Backend generator picks cards from pack pool and stores `matrixSize` in `uiData`
    - Web UI: image grid + target `original` word; wrong = shake + error sound; correct = flip to translation then disappear
    - Admin: question type selector + matrix size form; JSON (de)serialization + vitest coverage

### Mobile Application (mnemo_cards)
- **Framework**: Flutter
- **Status**: Active development
- **Key Features**: Cross-platform mobile app

### Backend (mnemo_cards_backend)
- **Framework**: Dart with Shelf
- **Status**: Production ready
- **Key Features**: API, authentication, data management
- **Recent Updates**:
  - **Card Voices: Stop Returning base64**: `/api/v2/packs/.../voices` now returns a direct `url` to audio
    - Admin voice uploads are persisted to `data/voice/` and DB stores only a file name (no base64)
    - Public voice list heals legacy base64-in-DB by migrating to file on first read
    - `/api/v2/voice/<voiceId>` serves bytes (or redirects for remote URLs)
  - **User Telegram Field**: Added telegram field to user model
    - Added `telegram` field to `UserModel` and `UserDto` alongside `email`
    - Added `telegram` column to `users` table in database (migration v2→v3)
    - Updated all authentication flows (Google OAuth, Telegram Web App, Telegram bot)
    - Telegram usernames now stored in `telegram` field instead of `email`
    - Added comprehensive unit tests for UserModel and UserDto telegram field
    - Migration automatically moves telegram usernames from email to telegram field
  - **Generated Tests Cleanup**: Fixed generated tests accumulating over time
    - Fixed linking bug: generated tests were created in DB but not linked to packs (caused orphan tests)
    - Added cron cleanup to purge orphan `version='generated'` tests and hard-delete old soft-deleted generated tests (TTL)
    - Added DAO helpers and a focused unit test for the cleanup logic
    - Added regression test to ensure `updateGeneratedTests()` creates a pack link
  - **Matrix Test (image selection)**: Added matrix question generator + API storage support (cards auto-generated if missing)

### Common Libraries
- **mnemo_cards_common**: Shared models and utilities
- **mnemo_cards_common_backend**: Backend-specific common code
- **mnemo_cards_frontend_common**: Frontend-specific common code

## Testing

### Unit Tests
- **Coverage**: Basic test coverage implemented
- **Status**: Ongoing - needs expansion

### Integration Tests
- **Status**: Minimal - needs implementation

### E2E Tests
- **Status**: Not implemented

## Deployment Pipeline

### CI/CD Status
- **Platform**: Forgejo Actions (self-hosted)
- **Triggers**: Push to master branch
- **Jobs**:
  - Backend deployment
  - Web application deployment
  - Admin panel deployment (improved portability)
  - Telegram bot deployment
  - Nginx configuration deployment
  - Service verification

- **Deployment Script Improvements**:
  - Enhanced admin panel deployment script portability
  - Script can now be run from any directory within the project
  - Automatic project root detection and navigation
  - Improved error handling and user feedback

### Environments
- **Production**: `147.45.152.129` (mnemo-cards.online)
- **Development**: Local development environments

## Performance Metrics

### Target Metrics
- **Page Load Time**: < 3 seconds
- **API Response Time**: < 500ms
- **Uptime**: 99.9%

### Current Status
- Basic monitoring in place
- Performance optimization ongoing

## Security

### Implemented
- HTTPS enforcement
- SSL/TLS certificates (Let's Encrypt for all domains including admin.mnemo-cards.online)
- Automated SSL certificate renewal
- Basic firewall rules
- Service isolation

### Planned
- Advanced security headers
- Rate limiting
- Intrusion detection
- Regular security audits

---

*Last updated: December 18, 2025*