Go to file

Michael b7306a963a Migration from SQlite3 to PostgreSQL (#1 )

* Migrate from SQLite to PostgreSQL for dev and prod environments

- Replace better-sqlite3 with pg library in backend
- Update database.js to use PostgreSQL connection pooling
- Convert migrations.sql to PostgreSQL syntax with proper triggers and constraints
- Convert seeds.sql to PostgreSQL syntax with JSONB for colors and ON CONFLICT handling
- Update docker-compose.yml with PostgreSQL service and db-migrate container
- Update deploy.sh to generate production docker-compose with PostgreSQL configuration
- Configure environment variables for database connection (DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD)

* Update database models to use PostgreSQL async API

- Convert User.js from better-sqlite3 to PostgreSQL async queries
  - Use parameterized queries with ,  placeholders
  - Update all methods to use async/await
  - Use result.rowCount instead of result.changes
  - Use result.rows[0].id for RETURNING clause results

- Convert Commander.js from better-sqlite3 to PostgreSQL async queries
  - Implement proper async methods with pg library
  - Update JSONB color handling (no longer needs JSON.parse/stringify)
  - Use ILIKE for case-insensitive search instead of LIKE
  - Use proper numeric casting for win rate calculations

- Convert Game.js from better-sqlite3 to PostgreSQL async queries
  - All query methods now properly async
  - Update boolean handling (true/false instead of 1/0)
  - Use ILIKE for case-insensitive commander name search
  - Use RETURNING clause instead of lastInsertRowid

All models now use dbManager.query(), dbManager.get(), and dbManager.all() methods

* Add PostgreSQL cleanup and repository pattern for improved DB abstraction

Database Improvements:
- Fix migrate.js to use async PostgreSQL API with proper error handling
- Update .env.example to reflect PostgreSQL configuration variables
- Update GitHub Actions workflow to generate production docker-compose with PostgreSQL

Architectural Improvements:
- Create base Repository class providing common CRUD operations
- Implement UserRepository for user-specific database operations
- Implement CommanderRepository for commander-specific database operations
- Implement GameRepository for game-specific database operations
- All repositories use parameterized queries to prevent SQL injection
- Centralized database access patterns for better maintainability

Benefits:
- Cleaner separation of concerns (repositories handle data access)
- Reusable repository pattern can be extended for new entities
- Better error handling and transaction support
- Improved code organization and maintainability
- All database queries now properly handle PostgreSQL async operations

* Add comprehensive PostgreSQL migration documentation

- Complete migration summary with before/after comparison
- Detailed changes to each component
- Architecture improvements and benefits
- Repository pattern explanation
- Quick start guide for development and production
- Deployment instructions
- Testing guidelines
- Verification checklist

* Fix Docker build: update package-lock.json and npm syntax

- Run npm install to update package-lock.json with pg dependencies
- Replace deprecated --only=production with --omit=dev (npm 7+)
- Resolves Docker build error about missing pg packages in lock file

* Add migration status document

- Executive summary of completed migration
- Detailed commits history with verification
- Architecture before/after comparison
- Deployment instructions (dev & prod)
- Testing procedures
- Performance characteristics
- Troubleshooting guide
- Rollback instructions (if needed)
- Final sign-off for production readiness

* Add comprehensive deployment checklist

- Pre-deployment verification checklist
- Development deployment step-by-step guide
- Production deployment procedures
- Rollback instructions for emergency cases
- Monitoring and maintenance procedures
- Common issues and solutions
- Performance monitoring commands
- Sign-off checklist for deployment readiness

* Fix PostgreSQL user authentication in docker-compose

- Use postgres superuser instead of creating custom user
- Add init-db script directory for database initialization
- Update docker-compose to mount init scripts
- Simplify credentials: use 'postgres' user for dev
- Update .env.example with correct default credentials
- Health check now uses postgres user

This resolves the 'role edh_user does not exist' error on container startup.
The postgres superuser can create and manage databases and migrations.

* Add Docker Compose testing guide

- Prerequisites checklist
- Step-by-step startup instructions
- Service verification procedures
- API and database testing commands
- Frontend verification steps
- Troubleshooting guide for common issues
- Cleanup procedures
- Expected results checklist

* Fix PostgreSQL password authentication - use correct default user

- Remove incorrect POSTGRES_USER setting (defaults to postgres)
- Set POSTGRES_PASSWORD=edh_password for the default postgres user
- Set POSTGRES_DB=edh_stats to create database automatically
- Update db-migrate and backend services to use password: edh_password
- Update .env.example with correct credentials

PostgreSQL Docker image automatically creates the 'postgres' superuser
when POSTGRES_PASSWORD is set. This resolves the authentication error.

* Add final verification document for completed migration

- Complete migration status verification
- All issues resolved checklist
- Final commit log with all 10 commits
- Quick start command for docker-compose
- Development credentials reference
- Complete list of deliverables
- Documentation index
- Ready-to-deploy status confirmation

* Fix PostgreSQL initialization and SQL migration execution

- Fix 01-init.sql: Remove invalid MySQL syntax and rely on POSTGRES_DB for database creation
- Fix database.js: Execute entire migration/seed SQL files as single queries instead of splitting by semicolon
  This prevents issues with multi-statement SQL constructs (functions, views, triggers)
- Fix docker-compose.yml: Add listen_addresses=* to allow connections from Docker network containers
  and add PGPASSWORD to healthcheck for proper password authentication

All services now start successfully:
- PostgreSQL accepts connections from Docker network
- Migrations run without errors
- Seed data is properly inserted
- Backend API starts and health checks pass
- Database schema with tables, views, and triggers created correctly

* Fix production docker-compose configuration in deploy.sh

- Add listen_addresses=* to PostgreSQL command for Docker network connectivity
- Use 'postgres' superuser instead of DB_USER variable (matches development setup)
- Fix PostgreSQL healthcheck to include PGPASSWORD environment variable
- Fix frontend healthcheck to check root path instead of non-existent /health endpoint
- Add resource limits to frontend container for consistency
- Update .env documentation to reflect correct PostgreSQL user

* Fix DB_USER configuration consistency

- Change default DB_USER in database.js from 'edh_user' to 'postgres'
- Aligns with .env.example, docker-compose.yml, and deploy.sh
- Add clarifying comment in .env.example explaining superuser requirement
- DB_USER must be a superuser to run migrations and create schema objects

The PostgreSQL superuser 'postgres' is created automatically by the Docker image
and has the necessary privileges for all application operations.

* Add DB_SEED environment variable to toggle automatic seeding

- Add DB_SEED environment variable to db-migrate service (default: false)
- Update migrate.js to check DB_SEED and automatically seed if enabled
- Fix seeds.sql ON CONFLICT clauses and sequence resets to use dynamic MAX(id)
- Seeds can now be triggered by setting DB_SEED=true in docker-compose or .env
- Add documentation to .env.example explaining DB_SEED option
- Update deploy.sh to support DB_SEED in production configuration

This allows developers to quickly populate test data during development
without manual seeding commands, while keeping it opt-in for clean databases.

* Fix Commander model: properly convert colors array to JSON for JSONB storage

- Convert JavaScript arrays to JSON strings before inserting into JSONB column
- Add ::jsonb type cast in SQL queries for explicit JSONB conversion
- Handle both array and string inputs in create() and update() methods
- Fixes 'invalid input syntax for type json' error when creating/updating commanders

The pg library doesn't automatically convert JS arrays to JSON, so we must
stringify them before passing to PostgreSQL. The ::jsonb cast ensures proper
type conversion in the database.

* Fix JSON parsing in routes: PostgreSQL JSONB is already parsed

PostgreSQL's pg library automatically parses JSONB columns into JavaScript objects.
The routes were incorrectly calling JSON.parse() on already-parsed JSONB data,
which would fail or cause errors.

Fixed in:
- backend/src/routes/commanders.js (3 occurrences)
- backend/src/routes/games.js (3 occurrences)
- backend/src/routes/stats.js (1 occurrence)

Changed from: JSON.parse(colors) or JSON.parse(commander_colors)
Changed to: colors || [] or commander_colors || []

This matches how the models already handle JSONB data correctly.

* Fix seeds.sql: correct bcrypt hash for password123

The previous bcrypt hash was incorrect and did not match 'password123'.
Generated the correct hash using bcryptjs with 12 rounds.

Correct credentials for seeded test users:
  - Username: testuser
    Password: password123

  - Username: magictg
    Password: password123

This allows developers to login to the application with seeded data.

* Fix stats routes: convert from SQLite to PostgreSQL async methods

- Replace db.prepare().get() with await dbManager.get()
- Replace db.prepare().all() with await dbManager.all()
- Update parameterized query placeholders from ? to $1, $2, etc
- Change boolean comparisons from 'won = 1' to 'won = TRUE' for PostgreSQL
- Remove unnecessary db.initialize() calls
- Both /api/stats/overview and /api/stats/commanders now working correctly

* Fix games routes: remove SQLite boolean conversions and unnecessary JSON parsing

- Remove boolean-to-integer conversion (was converting true/false to 1/0)
- Remove JSON.parse() on JSONB colors column (PostgreSQL pg driver already parses JSONB)
- Fix in both POST create response and PUT update response
- Colors array now correctly returned as already-parsed JavaScript array
- Boolean fields now correctly returned as native boolean type

* Fix frontend: remove JSON.parse() on colors from API responses

- colors field is now pre-parsed array from PostgreSQL JSONB
- Simplified stats.html line 124: remove JSON.parse(stat.colors)
- Simplified dashboard.html line 279: remove defensive type checking for colors
- Frontend now properly handles colors as JavaScript arrays

* Simplify: remove defensive type checking for commanderColors in
dashboard

- game.commanderColors is always an array from PostgreSQL JSONB
- Changed from complex ternary to simple: game.commanderColors || []

* feat: improve environment variable handling in docker-compose and .env.example

- Add RATE_LIMIT_WINDOW and RATE_LIMIT_MAX to .env.example (commented for now)
- Update docker-compose.yml to use environment variables with defaults
  - All DB_* variables now use default format
  - NODE_ENV, JWT_SECRET, CORS_ORIGIN, LOG_LEVEL, ALLOW_REGISTRATION now respect env vars
  - DB_SEED now uses environment variable
- Improves flexibility for development, testing, and production deployments
- Maintains backward compatibility with defaults
- Reduces hardcoded values and increases configurability

* fix: use DB_PASSWORD environment variable in postgres healthcheck

- PGPASSWORD in healthcheck was hardcoded to 'edh_password'
- Changed to use ${DB_PASSWORD:-edh_password} for consistency
- Ensures healthcheck respects DB_PASSWORD environment variable
- Fixes issue where custom DB_PASSWORD would cause healthcheck to fail

* fix: make PostgreSQL external port configurable via DB_PORT

- Changed postgres port mapping from hardcoded '5432:5432' to '${DB_PORT:-5432}:5432'
- Allows users to expose PostgreSQL on different external port via DB_PORT env variable
- Internal container port remains 5432 (unchanged)
- Enables non-standard port usage in constrained environments
- Maintains backward compatibility with default of 5432

* fix: update production docker-compose template in deploy.sh for environment variables

Changes to generated docker-compose.prod.deployed.yml:

Postgres Service:
- Added configurable external port: ${DB_PORT:-5432}:5432
- Ensures port mapping respects DB_PORT environment variable

DB-Migrate Service:
- DB_HOST: postgres -> ${DB_HOST:-postgres}
- DB_PORT: 5432 -> ${DB_PORT:-5432}
- DB_USER: postgres -> ${DB_USER:-postgres}
- Maintains configuration consistency with development

Backend Service:
- DB_HOST: postgres -> ${DB_HOST:-postgres}
- DB_PORT: 5432 -> ${DB_PORT:-5432}
- DB_USER: postgres -> ${DB_USER:-postgres}
- LOG_LEVEL: warn -> ${LOG_LEVEL:-warn}
- Removed hardcoded RATE_LIMIT_* variables (not used yet)
- All variables now properly parameterized

Documentation:
- Updated .env example to include DB_USER, LOG_LEVEL, DB_SEED
- Better guidance for production deployment

Ensures production deployments have same flexibility as development

* fix: update GitHub Actions workflow for PostgreSQL and environment variables

Postgres Service:
- POSTGRES_USER: edh_user -> postgres (matches .env.example and deploy.sh)
- POSTGRES_PASSWORD: change-this-in-production -> edh_password (matches .env.example)
- Added ports configuration: ${DB_PORT:-5432}:5432 (allows external access)
- Fixed healthcheck to use PGPASSWORD and proper variable syntax

DB-Migrate Service:
- DB_HOST: postgres -> ${DB_HOST:-postgres}
- DB_PORT: 5432 -> ${DB_PORT:-5432}
- DB_USER: edh_user -> postgres
- DB_PASSWORD: change-this-in-production -> edh_password
- Added DB_SEED=${DB_SEED:-false}

Backend Service:
- DB_HOST: postgres -> ${DB_HOST:-postgres}
- DB_PORT: 5432 -> ${DB_PORT:-5432}
- DB_USER: edh_user -> postgres
- DB_PASSWORD: change-this-in-production -> edh_password
- JWT_SECRET: removed unsafe default (must be provided)
- LOG_LEVEL: warn -> ${LOG_LEVEL:-warn}

Ensures GitHub Actions workflow is consistent with:
- docker-compose.yml (development)
- deploy.sh (production script)
- .env.example (configuration template)

* feat: implement global rate limiting and request/response logging

- Added rateLimitConfig to jwt.js with configurable window (minutes) and max requests
- Integrated global rate limiting into server.js using RATE_LIMIT_WINDOW and RATE_LIMIT_MAX env vars
- Default: 100 requests per 15 minutes (overridable via environment)
- Added request/response logging hooks for debugging (logged at debug level)
- Logs include method, URL, IP, status code, and duration
- Updated .env.example to document rate limiting configuration

* docs: update README for PostgreSQL migration and new features

- Updated intro to mention PostgreSQL instead of SQLite
- Added rate limiting and request logging features to infrastructure
  section
- Updated Technology Stack to reflect PostgreSQL and rate-limiting
- Revised environment variables section with PostgreSQL config
- Added Custom Environment Variables section with examples
- Expanded Database section with PostgreSQL-specific details
- Added Tips & Common Operations for PostgreSQL management
- Updated Recent Changes to document Session 3 migration work
- Updated Development Notes for async database operations
- Added JSONB field documentation

* security: remove exposed PostgreSQL port from docker-compose

PostgreSQL no longer needs to be exposed to the host since:
- Backend container accesses postgres via internal Docker network
- DB_PORT=5432 is only for internal container connections, not port mapping
- Removes unnecessary attack surface in production

Changes:
- Removed 'ports:' section from postgres service in docker-compose.yml
- Removed port mapping from production deploy.sh template
- Clarified DB_PORT usage in .env.example (internal only)
- Added DB_USER to .env.example with explanation

Security Impact:
- PostgreSQL only accessible within Docker network
- Reduced container exposure to host network
- More secure production deployments

Tested:
- All services start successfully
- Backend connects to postgres via internal network
- Login works, database queries successful
- Frontend accessible on 8081, Backend on 3002

* refactor: remove hardcoded DB_PORT, use PostgreSQL standard port 5432

Simplified database configuration by removing configurable DB_PORT since
PostgreSQL always runs on standard port 5432:

Changes:
- Updated backend/src/config/database.js to hardcode port 5432
- Removed DB_PORT from all docker-compose services
- Removed DB_PORT from production deploy.sh template
- Updated .env.example with clearer documentation
- Clarified that port 5432 is not configurable

Benefits:
- Simpler configuration (fewer environment variables)
- Standard PostgreSQL port is expected behavior
- Reduced configuration surface area
- Still flexible: can adjust DB_HOST for different database servers

Tested:
- All services start successfully
- Database connections work via internal Docker network
- User authentication functional
- API endpoints respond correctly

* docs: update README to reflect DB_PORT removal and configuration simplification

Updated documentation to reflect latest changes:
- Removed DB_PORT from environment variables section (port 5432 is standard)
- Added note that PostgreSQL port is not configurable
- Clarified connection details (port 5432 is standard, not configurable)
- Updated project structure: postgres_data instead of database
- Added deployment script to project structure
- Updated Recent Changes section with configuration simplification details
- Added DB_SEED documentation to environment variables
- Improved clarity on which settings are configurable vs. standard

Emphasizes the security and simplicity improvements from removing
unnecessary port configuration.

* Remove migration docs and init scripts

* refactor: migrate routes from models to repositories

Replaced all data access layer calls in routes from Model classes to Repository classes.

Changes:
- auth.js: Now uses UserRepository instead of User model
  * User.create() → UserRepository.createUser()
  * User.findByUsername() → UserRepository.findByUsername()
  * User.findById() → UserRepository.findById()
  * User.verifyPassword() → UserRepository.verifyPassword()
  * User.updatePassword() → UserRepository.updatePassword()
  * User.updateUsername() → UserRepository.updateUsername()
  * User.updateProfile() → UserRepository.updateProfile()

- commanders.js: Now uses CommanderRepository instead of Commander model
  * Commander.create() → CommanderRepository.createCommander()
  * Commander.findByUserId() → CommanderRepository.getCommandersByUserId()
  * Commander.search() → CommanderRepository.searchCommandersByName()
  * Commander.findById() → CommanderRepository.findById()
  * Commander.update() → CommanderRepository.updateCommander()
  * Commander.delete() → CommanderRepository.deleteCommander()
  * Commander.getStats() → CommanderRepository.getCommanderStats()
  * Commander.getPopular() → CommanderRepository.getPopularCommandersByUserId()

- games.js: Now uses GameRepository instead of Game model
  * Game.findByUserId() → GameRepository.getGamesByUserId()
  * Game.findById() → GameRepository.getGameById()
  * Game.create() → GameRepository.createGame()
  * Game.update() → GameRepository.updateGame()
  * Game.delete() → GameRepository.deleteGame()
  * Game.exportByUserId() → GameRepository.exportGamesByUserId()

Benefits:
✅ Clean separation of concerns (routes vs data access)
✅ Better testability (can mock repositories)
✅ More maintainable (database logic centralized)
✅ Consistent patterns across all data access
✅ Easier to add caching or logging layers

Testing:
✓ All syntax checks pass
✓ Authentication working
✓ Commanders endpoint returning 5 commanders
✓ Games endpoint returning 16 games
✓ All endpoints functional

* refactor: remove unused model classes

Models (User, Commander, Game) have been fully replaced by their
corresponding Repository classes. All functionality is preserved in
the repositories with no loss of capability or breaking changes.

Deleted files:
- User.js (136 lines)
- Commander.js (195 lines)
- Game.js (204 lines)

Total: ~535 lines of unused code removed

Benefits:
✅ Cleaner codebase - no duplicate data access logic
✅ Single source of truth - repositories handle all data access
✅ Better maintainability - clear separation of concerns
✅ No confusion - developers only use repositories
✅ Follows DRY principle - no code duplication

Testing:
✓ All routes verified to use repositories only
✓ All endpoints tested and working
✓ Authentication (8 endpoints)
✓ Commanders (7 endpoints)
✓ Games (6 endpoints)
✓ Stats (read-only)

No breaking changes - all functionality identical to before.

* Configure DB env defaults and add health checks

- Use DB_USER, DB_PASSWORD, and DB_NAME with defaults in deploy.sh and
  docker-compose.yml
- Replace wget-based health check with curl to /health in the frontend
  service
- Remove listen_addresses configuration from Postgres in
  deploy/docker-compose
- Delete frontend/public/status.html

* Return camelCase game data and richer responses

* Add validation utilities and stricter schemas

* Update commanders.html

2026-01-17 21:14:10 +01:00

.github/workflows

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

backend

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

frontend

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

.env.example

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

.gitignore

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

deploy.sh

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

DEPLOYMENT_CHECKLIST.md

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

DEPLOYMENT.md

Add init-db service and update deployment docs

2026-01-15 10:02:13 +01:00

docker-compose.yml

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

QUICK_DEPLOY.md

Update frontend ports to 38080 and 30443 to avoid conflicts with other containers

2026-01-15 10:04:07 +01:00

README.md

Migration from SQlite3 to PostgreSQL (#1 )

2026-01-17 21:14:10 +01:00

TODO.md

Finish JSON export feature and simplify JWT config

2026-01-16 14:55:25 +01:00

README.md

EDH/Commander Stats Tracker

A lightweight, responsive web application for tracking Magic: The Gathering EDH/Commander games with comprehensive statistics and analytics. Built with Fastify (Node.js), PostgreSQL, and Alpine.js for optimal performance and scalability.

Features

✅ Implemented

Authentication & Users

Secure Authentication: JWT-based login/registration system with password hashing (HS512).
User Profile Management: View and edit user profile information.
Session Management: Persistent authentication with localStorage/sessionStorage support.
Configurable Registration: Toggle user registration on/off via ALLOW_REGISTRATION environment variable for controlled access.

Commander Management

CRUD Operations: Create, read, update, and delete Commander decks.
MTG Color Identity Picker: Interactive WUBRG color selection with visual indicators.
Search & Filter: Find commanders by name with real-time search.
Validation: Comprehensive name and color validation.
Popular Commanders: View your most-played commanders at a glance.

Game Logging

Game Result Tracking: Log wins and losses with detailed statistics.
Round Tracking: Record the number of rounds each game lasted.
Player Count: Track games with 2-8 players.
Special Conditions: Record specific win conditions:
- Did the starting player win?
- Did a Turn 1 Sol Ring player win?
Game Notes: Add custom notes to each game record (full-width text area with auto-sizing).
Commander Association: Link games to specific Commanders with automatic name/color display.
Edit History: Modify game records after logging with real-time UI updates.

Live Round Counter ⭐ (NEW)

Real-Time Tracking: Interactive counter with live elapsed time (HH:MM:SS).
Round Management: Increment/decrement rounds with large, easy-to-use buttons.
Game Duration: Automatic calculation of game elapsed time.
Average Time Calculation: Track average time per round.
Quick Jump: Jump to specific rounds (5, 7, 10) quickly.
Fullscreen Mode: Expand counter for better visibility during gameplay.
Persistent State: Game progress saved to localStorage and survives page refreshes.
24-Hour Auto-Reset: Counters older than 24 hours automatically reset.
Seamless Integration: Directly log games from the round counter with prefilled data.

Game Logging Workflow Integration ⭐ (NEW)

Smart Prefill: When ending a game from the round counter, the game logging form automatically populates with:
- Actual round count from the counter
- Game date (today's date)
- Auto-generated notes showing duration and round count
Auto-Open Form: Game logging form automatically displays when returning from the round counter.
Auto-Scroll: Form scrolls into view automatically for seamless UX.
One-Click Logging: Minimize manual data entry by prefilling common fields.

Statistics Dashboard

KPI Overview: Display total games, win rate, active decks, average rounds (dynamically loaded).
Commander Stats: Top commanders (5+ games) with game counts and win rates, sorted by most-played.
Recent Games: Latest 5 games with commander colors and results displayed.
Game Statistics: View statistics for individual commanders with comprehensive metrics.

Visualizations (Chart.js)

Win Rate by Color Identity: Doughnut chart showing performance by color combination.
Win Rate by Player Count: Bar chart showing win rates across different player counts.
Detailed Tables: Per-commander performance metrics and trends.

User Interface

Responsive Design: Mobile-friendly layout using Tailwind CSS.
Dark Theme: Professional dark color scheme with proper contrast.
Alpine.js Components: Lightweight, reactive UI without heavy frameworks.
Professional Navigation: Easy access to all major features.
Accessibility: Semantic HTML and accessible form controls.

Infrastructure & Deployment

Docker Support: Complete Docker and Docker Compose setup.
Development Environment: Pre-configured with hot-reload and logging.
Database: PostgreSQL 16 with connection pooling and automated migrations.
Automated Migrations: Database schema management on startup.
Rate Limiting: Configurable global rate limiting with per-endpoint overrides.
Request Logging: Comprehensive request/response logging for debugging.

🚧 Pending / Roadmap

Analytics & Insights

Advanced Trends: Historical performance trends over time (endpoints /api/stats/trends not yet implemented).
Win Rate Trends: Visualize win rate changes over weeks/months.
Player Count Analysis: Identify which player counts you perform best in.

Features

Commander Comparison: Direct head-to-head comparison tool (stats, win rates, matchups).
Deck Notes: Add longer notes/strategy notes to Commander decks.
Game Filters: Advanced filtering by date range, player count, color, etc.
Export Data: CSV/JSON export for external analysis.

System Features

Unit/Integration Tests: Comprehensive test suite for backend and frontend.
API Documentation: Swagger/OpenAPI documentation.
Performance Optimization: Database query optimization and caching.

Deployment & Security

HTTPS Configuration: Production-ready Nginx setup with SSL/TLS.
User Preferences: Store user settings (theme, preferences).
Password Reset: Forgot password functionality with email verification.

Technology Stack

Backend: Fastify (Node.js v20+)
Database: PostgreSQL 16 with connection pooling (pg library)
Frontend: Alpine.js, Tailwind CSS (CDN)
Visualization: Chart.js
Containerization: Docker & Docker Compose
Authentication: JWT with HS512 hashing
Password Security: bcryptjs with 12-round hashing
Rate Limiting: @fastify/rate-limit plugin with configurable limits

Quick Start

Prerequisites

Docker & Docker Compose (recommended)
Or: Node.js v20+, npm, and Python 3

Running with Docker (Recommended)

# Clone the repository
git clone <repository-url>
cd edh-stats

# Start the application
docker-compose up -d

# Access the application
# Frontend: http://localhost:8081
# Backend API: http://localhost:3002

Note: Default ports are 8081 (Frontend) and 3002 (Backend) to avoid conflicts. PostgreSQL runs on 5432.

Custom Environment Variables

You can customize the database and other settings by creating or editing .env:

# Copy the example to create your own
cp .env.example .env

# Edit .env with your preferred settings
nano .env

# Start with custom environment
docker-compose up -d

Common customizations:

# Change PostgreSQL password
DB_PASSWORD=your_secure_password

# Enable debug logging
LOG_LEVEL=debug

# Tighten rate limiting
RATE_LIMIT_WINDOW=5
RATE_LIMIT_MAX=50

# Disable user registration
ALLOW_REGISTRATION=false

Environment Variables Reference

Key environment variables you can configure in .env:

# PostgreSQL Database Configuration
DB_HOST=localhost                    # Database server hostname/IP
DB_NAME=edh_stats                    # Database name
DB_USER=postgres                     # Database user (must be superuser for migrations)
DB_PASSWORD=edh_password             # Database password (MUST be changed in production)
# PostgreSQL always uses standard port 5432 (not configurable)

# Application Configuration
NODE_ENV=development                 # Set to 'production' in production
LOG_LEVEL=info                       # Log level: debug, info, warn, error

# Security
JWT_SECRET=your-super-secure-jwt-secret-key-change-this-in-production

# CORS Configuration
CORS_ORIGIN=http://localhost:80

# User Registration - Set to 'true' to enable signup, 'false' to disable
ALLOW_REGISTRATION=true

# Rate Limiting (optional - default: 100 requests per 15 minutes)
RATE_LIMIT_WINDOW=15                 # Time window in MINUTES
RATE_LIMIT_MAX=100                   # Max requests per window

# Database Seeding (optional - for development only)
DB_SEED=false                        # Set to 'true' to auto-seed sample data on startup

# Database Connection Pooling (Advanced - optional)
# DB_POOL_MIN=2
# DB_POOL_MAX=10

Local Development

If you prefer running without Docker:

# Create .env file in root directory
cp .env.example .env
# Edit .env with your configuration

# Backend
cd backend
npm install
npm run dev  # Starts with hot-reload

# Frontend (in another terminal)
cd frontend
# Use any static file server, e.g., 'serve' or Python's http.server
npx serve public -p 8081
# OR
python3 -m http.server 8081 --directory public

Important

: The .env file must be in the root project directory, not in the backend folder. The application will automatically load it from there.

Project Structure

edh-stats/
├── backend/
│   ├── src/
│   │   ├── config/         # Database & Auth configuration
│   │   ├── database/       # Migrations & Seeds
│   │   ├── middleware/     # Fastify middleware
│   │   ├── models/         # Data access layer (Commander, Game, User)
│   │   ├── routes/         # API endpoint handlers
│   │   ├── utils/          # Utility functions
│   │   └── server.js       # Application entry point
│   ├── package.json        # Node.js dependencies
│   └── Dockerfile
├── frontend/
│   ├── public/
│   │   ├── css/            # Tailwind styles
│   │   ├── js/             # Alpine.js components
│   │   ├── components/     # Reusable HTML components
│   │   ├── *.html          # View files
│   │   └── round-counter.html  # Live round counter (NEW)
│   ├── tailwind.config.js  # Tailwind configuration
│   ├── package.json        # Node.js dependencies
│   └── Dockerfile
├── postgres_data/          # Persisted PostgreSQL data (Docker volume)
├── docs/                   # Documentation
├── FIXES.md                # Detailed list of fixes applied
├── FEATURES.md             # Feature documentation
├── docker-compose.yml      # Development orchestration
├── deploy.sh               # Production deployment script
└── README.md

API Endpoints

Authentication (`/api/auth`)

POST /register - Register new user
POST /login - Login user
GET /me - Get current user profile
PATCH /me - Update user profile
POST /change-password - Change password
POST /refresh - Refresh authentication token

Commanders (`/api/commanders`)

GET / - List/Search commanders
POST / - Create new commander
GET /popular - Get top commanders by games played
GET /:id - Get commander details
GET /:id/stats - Get commander statistics
PUT /:id - Update commander
DELETE /:id - Delete commander

Games (`/api/games`)

GET / - List games with pagination and filtering
POST / - Log new game result
GET /:id - Get game details
PUT /:id - Edit game record
DELETE /:id - Delete game record

Statistics (`/api/stats`)

GET /overview - Get user overview statistics (total games, win rate, etc.)
GET /commanders - Get detailed commander statistics with charts

Health Check

GET /api/health - Server and database health status

Usage Guide

Logging Into the Application

Navigate to http://localhost:8081
Use the registration or login form
After authentication, you'll be redirected to the dashboard

Managing Commanders

Click "Commanders" in the navigation
Click "Add Commander" to create a new deck
Select the color identity (WUBRG)
Edit or delete existing commanders from the list

Logging Games

Click "Log Game" in the navigation
Fill in the game details:
- Select your commander
- Choose number of players (2-8)
- Mark if you won or lost
- Record the number of rounds
- Check special conditions if applicable
Click "Log Game"

Using the Round Counter

Click "Start Round Counter" on the dashboard
Click "Start Game" to begin tracking
Use the large + button to increment rounds
Use the large − button to decrement rounds
View real-time elapsed time and average time per round
Click "End Game & Log Results" when finished
The game logging form will open with prefilled values

Viewing Statistics

Click "Statistics" in the navigation
View your KPI cards (Total Games, Win Rate, etc.)
See charts for win rate by color and player count
View detailed commander statistics

Development Notes

PostgreSQL Database Setup

Connection Details

Database: PostgreSQL 16 (containerized in Docker)
Connection Library: Node.js pg library (async/await)
Host: postgres (configurable via DB_HOST)
Port: 5432 (PostgreSQL standard port, not configurable)
Name: edh_stats (configurable via DB_NAME)
User: postgres (configured via DB_USER)
Connection Pool: Automatic pooling (configurable via DB_POOL_MIN/DB_POOL_MAX)

Migrations & Schema

Auto-migrations: Database schema automatically created on server startup
Migration File: src/database/migrations.sql
Seed Data: Optional test data can be seeded via DB_SEED=true
Foreign Keys: Enabled for data integrity

Database Objects

Tables: users, commanders, games, user_stats (summary)
Views:
- user_stats: Aggregates user-level statistics (total games, win rate, etc.)
- commander_stats: Aggregates per-commander statistics (shown for commanders with 5+ games)
JSONB Fields:
- commanders.colors: Color identity array stored as JSONB
- Automatically parsed by pg driver - no JSON.parse() needed in code

Tips & Common Operations

Reset Database

# Remove PostgreSQL volume to reset all data
docker compose down -v
docker compose up -d

View Database Directly

# Connect to PostgreSQL container
docker compose exec postgres psql -U postgres -d edh_stats

# List tables
\dt

# Exit
\q

Check Connection Pool Status The application logs connection pool info at startup. To debug connection issues, set LOG_LEVEL=debug to see detailed connection logging.

Frontend State Management

Alpine.js components handle all state management
No external state management library needed
Components:
- app(): Main dashboard and page initialization
- commanderManager(): Commander CRUD operations
- gameManager(): Game logging and editing
- roundCounterApp(): Real-time round counter with game timing
Authentication tokens stored in localStorage (persistent) or sessionStorage (session-only)
Data persistence: localStorage for round counter state
Dynamic content loading: Partial HTML pages loaded and inserted via loaders

Authentication Flow

User registers with username and password
Password hashed with bcryptjs (12 rounds)
JWT token generated (HS512 algorithm)
Token stored in browser (localStorage/sessionStorage)
Token validated on protected routes
Automatic token validation on component initialization

Error Handling

All API errors return appropriate HTTP status codes
Validation errors provide detailed feedback
Database errors logged but generic messages sent to client
Frontend gracefully handles network failures

Recent Changes & Fixes

Major: SQLite → PostgreSQL Migration ✅

Database: Migrated from SQLite (better-sqlite3) to PostgreSQL 16
Async/Await: Converted all database operations to async/await pattern
Connection Pooling: Uses pg library with automatic connection pooling
JSONB Support: Color arrays now stored as PostgreSQL JSONB type (auto-parsed by pg driver)
No Breaking Changes: Fully backward compatible with existing frontend

Configuration Simplification

Removed DB_PORT: Now uses PostgreSQL standard port 5432 (not configurable)
Cleaner Environment: Only essential variables need configuration
Security: PostgreSQL port no longer exposed to host network
Simplified Docs: Better clarity on what settings are configurable vs. standard

Rate Limiting & Logging

Global Rate Limiting: Configurable via RATE_LIMIT_WINDOW (minutes) and RATE_LIMIT_MAX (requests)
Default: 100 requests per 15 minutes (per IP address)
Per-Endpoint Limits: Individual endpoints have their own stricter limits
Request Logging: Comprehensive request/response logging at debug level
Logs Include: Method, URL, IP, status code, response time

Environment Variables (Simplified)

All configuration: Centralized in .env file
PostgreSQL Connection: DB_HOST, DB_NAME, DB_USER, DB_PASSWORD (port is standard 5432)
Rate Limiting: RATE_LIMIT_WINDOW, RATE_LIMIT_MAX (optional)
Logging: LOG_LEVEL (debug, info, warn, error)
Database Seeding: DB_SEED (optional, for development)

Previous Updates (Session 2)

Top Commanders Display: Fixed filtering to show all commanders with 5+ games, sorted by most-played first
Game Notes UI: Expanded textarea width to full width with improved sizing (5 rows)
Data Consistency: Fixed camelCase/snake_case field naming throughout API and frontend
Environment Configuration: Fixed .env file loading from root directory in Docker containers
Registration Control: Added ALLOW_REGISTRATION environment variable to toggle signup availability
Game API Response: Ensured all game endpoints return complete commander information (name, colors)
Form Validation: Improved notes field handling to prevent null value validation errors
Frontend Error Handling: Fixed Alpine.js key binding issues in top commanders template

Previous Session Fixes

This version includes 19+ bug fixes and improvements addressing:

SQL parameter mismatches and injection vulnerabilities
Boolean type conversion issues in form submissions
Invalid Alpine.js expressions and duplicate elements
Corrupted SVG paths in UI components
Field name mismatches between frontend and backend
Color parsing and null/undefined value handling
Tailwind dark mode conflicts with system theme
Navbar text visibility issues

See FIXES.md for detailed documentation of all fixes.

Future Enhancements

Real-time multiplayer game tracking
Advanced statistical analysis and trends
Integration with MTG databases for card suggestions
Mobile native application
Live notifications for game updates
Keyboard shortcuts for faster game logging
Voice commands for hands-free operation
Cloud backup and sync

License

MIT

Support

For bug reports or feature requests, please create an issue in the repository.

Languages

Svelte 39.8%

JavaScript 37.8%

Shell 10.3%

CSS 9.9%

PLpgSQL 1.6%

Other 0.6%

README.md Unescape Escape

EDH/Commander Stats Tracker

Features

✅ Implemented

Authentication & Users

Commander Management

Game Logging

Live Round Counter ⭐ (NEW)

Game Logging Workflow Integration ⭐ (NEW)

Statistics Dashboard

Visualizations (Chart.js)

User Interface

Infrastructure & Deployment

🚧 Pending / Roadmap

Analytics & Insights

Features

System Features

Deployment & Security

Technology Stack

Quick Start

Prerequisites

Running with Docker (Recommended)

Custom Environment Variables

Environment Variables Reference

Local Development

Project Structure

API Endpoints

Authentication (/api/auth)

Commanders (/api/commanders)

Games (/api/games)

Statistics (/api/stats)

Health Check

Usage Guide

Logging Into the Application

Managing Commanders

Logging Games

Using the Round Counter

Viewing Statistics

Development Notes

PostgreSQL Database Setup

Connection Details

Migrations & Schema

Database Objects

Tips & Common Operations

Frontend State Management

Authentication Flow

Error Handling

Recent Changes & Fixes

Latest Updates (Session 3 - PostgreSQL Migration & Refinements)

Major: SQLite → PostgreSQL Migration ✅

Configuration Simplification

Rate Limiting & Logging

Environment Variables (Simplified)

Previous Updates (Session 2)

Previous Session Fixes

Future Enhancements

License

Support

README.md

Authentication (`/api/auth`)

Commanders (`/api/commanders`)

Games (`/api/games`)

Statistics (`/api/stats`)