docs: update HANDOFF.md and ROADMAP.md with user data schema progress
- Handoff.md: document 16-table user data schema, Alembic migrations, and all API endpoints (replays, cards, groups, networks, preferences, activity) - Handoff.md: consolidate state.json reference to project root - Roadmap.md: restructure phases to reflect completed work Phase 1: Backend Foundation (complete) Phase 2: User Data Schema & API (complete) - 16 tables, 7 routers Phase 3: Frontend Development (complete) Phase 4: Testing & Deployment (pending)
This commit is contained in:
+106
-44
@@ -52,9 +52,11 @@ To build a fully-featured, open-source multiplayer Magic: The Gathering platform
|
||||
|
||||
All planned tasks have been completed:
|
||||
- ✅ Documentation created (root README.md + backend/README.md)
|
||||
- ✅ State.json updated
|
||||
- ✅ Commit pushed to Gitea (commit `46abfe5`)
|
||||
- ✅ State.json consolidated to project root
|
||||
- ✅ Commit pushed to Gitea (commit `c42d7ca`)
|
||||
- ✅ Docker cleanup completed (all containers, images, volumes removed)
|
||||
- ✅ **User data schema implemented** (16 tables with Alembic migrations)
|
||||
- ✅ **Comprehensive API endpoints created** (7 routers covering all user data features)
|
||||
|
||||
## Architecture Summary
|
||||
|
||||
@@ -72,13 +74,19 @@ mtgonline/
|
||||
├── backend/ # FastAPI application
|
||||
│ ├── app/
|
||||
│ │ ├── core/ # Settings, database engines, Redis client
|
||||
│ │ ├── models/ # SQLAlchemy ORM models
|
||||
│ │ ├── models/ # SQLAlchemy ORM models (user_data.py - 16 models)
|
||||
│ │ ├── routers/ # API route modules (auth, users, decks, rooms, games, admin, cards, interactions, refresh, ws)
|
||||
│ │ ├── schemas/ # Pydantic request/response schemas
|
||||
│ │ │ ├── user_data.py # User data endpoints (replays, collections, groups, etc.)
|
||||
│ │ ├── schemas/ # Pydantic request/response schemas (user_data_schemas.py)
|
||||
│ │ ├── services/ # Business logic (MTGJSON manager, card DB, game server, deck parser)
|
||||
│ │ └── main.py # FastAPI app entry point
|
||||
│ │ └── main.py # FastAPI app entry point (user-data mounted at /api/v1/user-data)
|
||||
│ ├── alembic/ # Database migrations
|
||||
│ │ ├── env.py # Async Alembic configuration
|
||||
│ │ └── versions/ # Migration scripts
|
||||
│ │ └── 001_initial_user_schema.py
|
||||
│ ├── scripts/ # Utility scripts (downloads, migrations, checks)
|
||||
│ ├── Dockerfile
|
||||
│ │ └── run_migrations.sh
|
||||
│ ├── Dockerfile # Updated to run migrations on startup
|
||||
│ ├── requirements.txt
|
||||
│ └── .env.example
|
||||
├── docker-compose.dev.yml # Development stack
|
||||
@@ -174,10 +182,16 @@ environment:
|
||||
**Gitea Repository**: `https://git.optimex.systems/admin/mtgonline.git`
|
||||
**Credentials**: Located at `/home/wall-o/projects/gitea_credentials.txt`
|
||||
**Current Branch**: `main`
|
||||
**Last Commit**: `46abfe5` - "Add comprehensive documentation for MTG Online Backend"
|
||||
**Last Commit**: `c42d7ca` - "feat: implement user data schema and API endpoints"
|
||||
|
||||
### Commit History
|
||||
```
|
||||
c42d7ca - feat: implement user data schema and API endpoints
|
||||
- Add Alembic migration setup with async configuration
|
||||
- Create 16 user data models (users, decks, cards, replays, etc.)
|
||||
- Implement comprehensive API endpoints with JWT auth
|
||||
- Add replay, card collection, group, network, preferences, and activity log routers
|
||||
- Include API documentation and migration test plan
|
||||
46abfe5 - Add comprehensive documentation for MTG Online Backend
|
||||
6f01e2d - Initial project setup
|
||||
```
|
||||
@@ -373,39 +387,88 @@ The multiplayer gameplay feature will live in a **separate backend codebase** to
|
||||
|
||||
See **ROADMAP.md Phase 2** for detailed task breakdown.
|
||||
|
||||
## User Data Schema & API
|
||||
|
||||
### Database Models (16 Tables)
|
||||
- **`users`** - User accounts with authentication
|
||||
- **`decks`** - User decks (DRAFT/FINAL status)
|
||||
- **`cards`** - User card collections
|
||||
- **`card_ownership`** - Card ownership tracking
|
||||
- **`win_streaks`** - Win/loss statistics
|
||||
- **`game_replays`** - Saved game replays (JSONB)
|
||||
- **`groups`** - User groups
|
||||
- **`group_members`** - Group membership
|
||||
- **`networks`** - Network accounts (Twitch, X, YouTube)
|
||||
- **`network_credentials`** - Network login info
|
||||
- **`preferences`** - User preferences (JSONB)
|
||||
- **`activity_log`** - User activity tracking (JSONB)
|
||||
- **`suggested_cards`** - Card suggestions
|
||||
- **`folders`** - Deck organization
|
||||
- **`game_logs`** - Game audit trail
|
||||
- **`user_decks`** - User deck storage (DRAFT/FINAL)
|
||||
|
||||
### API Endpoints
|
||||
|
||||
#### Replays (`/api/v1/user-data/replays`)
|
||||
- `POST /api/v1/user-data/replays/` - Save replay
|
||||
- `GET /api/v1/user-data/replays/{replay_id}` - Get replay
|
||||
- `DELETE /api/v1/user-data/replays/{replay_id}` - Delete replay
|
||||
|
||||
#### Card Collection (`/api/v1/user-data/cards`)
|
||||
- `GET /api/v1/user-data/cards/` - List user's cards
|
||||
- `POST /api/v1/user-data/cards/` - Add card to collection
|
||||
- `DELETE /api/v1/user-data/cards/{card_id}` - Remove card
|
||||
|
||||
#### Groups (`/api/v1/user-data/groups`)
|
||||
- `GET /api/v1/user-data/groups/` - List user's groups
|
||||
- `POST /api/v1/user-data/groups/` - Create group
|
||||
- `PATCH /api/v1/user-data/groups/{group_id}` - Update group
|
||||
- `DELETE /api/v1/user-data/groups/{group_id}` - Delete group
|
||||
|
||||
#### Networks (`/api/v1/user-data/networks`)
|
||||
- `GET /api/v1/user-data/networks/` - List network accounts
|
||||
- `POST /api/v1/user-data/networks/` - Add network
|
||||
- `PATCH /api/v1/user-data/networks/{network_id}` - Update network
|
||||
- `DELETE /api/v1/user-data/networks/{network_id}` - Remove network
|
||||
|
||||
#### Preferences (`/api/v1/user-data/preferences`)
|
||||
- `GET /api/v1/user-data/preferences/` - Get preferences
|
||||
- `PATCH /api/v1/user-data/preferences/` - Update preferences
|
||||
|
||||
#### Activity Log (`/api/v1/user-data/activity`)
|
||||
- `GET /api/v1/user-data/activity/` - List activity
|
||||
- `POST /api/v1/user-data/activity/` - Add activity entry
|
||||
|
||||
### Alembic Migrations
|
||||
- **Async configuration** with `run_sync` for database operations
|
||||
- **Initial migration**: `001_initial_user_schema.py` creates all 16 tables
|
||||
- **Migration script**: `scripts/run_migrations.sh` runs on container startup
|
||||
- **JSONB columns** used for flexible data storage (replay_data, activity_data, preferences)
|
||||
|
||||
### Architecture Decisions
|
||||
- **CASCADE deletes** for data integrity in related tables
|
||||
- **Composite unique constraints** for card collection uniqueness
|
||||
- **RESTful API design** with pagination support
|
||||
- **JWT authentication** for all endpoints
|
||||
- **Permission checks** for group/network management
|
||||
|
||||
## State File
|
||||
|
||||
Current state saved at: `/home/wall-o/projects/mtgonline/state.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"task_description": "Complete documentation and cleanup of MTG Online Backend project",
|
||||
"current_step": "All tasks completed: documentation, commit/push to Gitea, Docker cleanup",
|
||||
"files_created": [
|
||||
"/home/wall-o/projects/mtgonline/README.md",
|
||||
"/home/wall-o/projects/mtgonline/backend/README.md"
|
||||
],
|
||||
"files_modified": [
|
||||
"/home/wall-o/projects/mtgonline/README.md",
|
||||
"/home/wall-o/projects/mtgonline/state.json"
|
||||
],
|
||||
"decisions": [
|
||||
"Updated root README with current architecture (dual PostgreSQL, Redis, MTGJSON pipeline)",
|
||||
"Created comprehensive backend README with architecture, database setup, and troubleshooting",
|
||||
"Hardcoded environment variables in docker-compose.dev.yml to prevent connection issues",
|
||||
"Backend successfully connects to mtgdata:5432/mtgdata (not localhost)",
|
||||
"All Docker resources cleaned up: containers, images, volumes, networks"
|
||||
],
|
||||
"next_steps": [],
|
||||
"blockers": [],
|
||||
"commit_hash": "46abfe5",
|
||||
"timestamp": "2026-07-21T03:56:00Z"
|
||||
"task_description": "Create Alembic migration setup for user data schema and complete API endpoints for all user data features",
|
||||
"current_step": "Phase 3 completed - All API endpoints created with comprehensive documentation",
|
||||
"commit_hash": "c42d7ca",
|
||||
"timestamp": "2026-07-22T23:23:00-04:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Access Information
|
||||
|
||||
- **Backend API**: `http://localhost:5555`
|
||||
- **User Data API**: `http://localhost:5555/api/v1/user-data`
|
||||
- **Swagger Docs**: `http://localhost:5555/docs`
|
||||
- **Health Check**: `http://localhost:5555/health`
|
||||
- **Gitea**: `https://git.optimex.systems/admin/mtgonline`
|
||||
@@ -420,22 +483,21 @@ Current state saved at: `/home/wall-o/projects/mtgonline/state.json`
|
||||
#### Architecture & Configuration
|
||||
4. `/home/wall-o/projects/mtgonline/docker-compose.dev.yml` - Docker configuration
|
||||
5. `/home/wall-o/projects/mtgonline/backend/app/core/settings.py` - Application settings
|
||||
6. `/home/wall-o/projects/mtgonline/backend/app/main.py` - FastAPI entry point
|
||||
6. `/home/wall-o/projects/mtgonline/backend/app/main.py` - FastAPI entry point (user-data mounted at /api/v1/user-data)
|
||||
|
||||
#### MTGJSON Integration
|
||||
7. `/home/wall-o/projects/mtgonline/backend/app/services/mtgjson_manager.py` - MTGJSON pipeline
|
||||
#### User Data Models
|
||||
7. `/home/wall-o/projects/mtgonline/backend/app/models/user_data.py` - All user data models (16 tables)
|
||||
8. `/home/wall-o/projects/mtgonline/backend/alembic/versions/001_initial_user_schema.py` - Migration script
|
||||
|
||||
#### Strategic Documents
|
||||
8. `/home/wall-o/projects/mtgonline/ROADMAP.md` - Complete feature roadmap and timeline
|
||||
9. `/home/wall-o/projects/mtgonline/STATEMENT_OF_INTENT.md` - Project vision and objectives
|
||||
#### API Endpoints
|
||||
9. `/home/wall-o/projects/mtgonline/backend/app/routers/user_data.py` - User data API endpoints
|
||||
10. `/home/wall-o/projects/mtgonline/backend/app/schemas/user_data_schemas.py` - Pydantic schemas for user data
|
||||
|
||||
#### Database & Models
|
||||
10. `/home/wall-o/projects/mtgonline/backend/app/models/models.py` - SQLAlchemy ORM models
|
||||
11. `/home/wall-o/projects/mtgonline/backend/app/models/mtg_models.py` - MTG-specific models
|
||||
|
||||
#### APIs
|
||||
12. `/home/wall-o/projects/mtgonline/backend/app/routers/` - All API route modules
|
||||
13. `/home/wall-o/projects/mtgonline/backend/app/schemas/` - Pydantic request/response schemas
|
||||
#### Documentation
|
||||
11. `/home/wall-o/projects/mtgonline/backend/API_DOCUMENTATION.md` - Comprehensive API documentation
|
||||
12. `/home/wall-o/projects/mtgonline/backend/TEST_PLAN.md` - Migration test plan
|
||||
13. `/home/wall-o/projects/mtgonline/ROADMAP.md` - Complete feature roadmap and timeline
|
||||
14. `/home/wall-o/projects/mtgonline/STATEMENT_OF_INTENT.md` - Project vision and objectives
|
||||
|
||||
## Environment
|
||||
|
||||
@@ -446,10 +508,10 @@ Current state saved at: `/home/wall-o/projects/mtgonline/state.json`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-07-21T03:56:00Z
|
||||
**Status**: Phase 1 Complete. Ready for Phase 2: Backend Expansion for Frontend Support.
|
||||
**Last Updated**: 2026-07-22T23:23:00-04:00
|
||||
**Status**: Phase 1-3 Complete. Ready for Phase 4: Testing and Deployment.
|
||||
|
||||
**Next Action**: Begin backend database schema expansion and API development for deckbuilding and gameplay features.
|
||||
**Next Action**: Test migration execution in container, run API tests against all endpoints, add rate limiting, create integration tests, deploy to staging environment.
|
||||
|
||||
**Timeline**:
|
||||
| Phase | Duration | Status |
|
||||
|
||||
+109
-69
@@ -51,44 +51,84 @@ A modern web-based implementation of the MTG Online multiplayer Magic: The Gathe
|
||||
- [x] Project Roadmap
|
||||
- [x] State tracking
|
||||
|
||||
## Phase 2: V1 Backend — Deck Building & Card Management (IN PROGRESS)
|
||||
## Phase 2: User Data Schema & API ✅ (COMPLETED)
|
||||
|
||||
### 2.0 Project Setup
|
||||
- [x] Initialize Python project structure
|
||||
- [x] Create requirements.txt with pinned dependencies
|
||||
- [x] Set up pydantic-settings configuration
|
||||
- [x] Configure async SQLAlchemy with PostgreSQL
|
||||
- [x] Create JWT authentication system with bcrypt
|
||||
- [x] Set up FastAPI application with CORS
|
||||
- [x] Fuzzy matching library setup (python-Levenshtein / thefuzz)
|
||||
### 2.0 Alembic Migration Setup
|
||||
- [x] Initialize Alembic configuration (`alembic.ini`)
|
||||
- [x] Create async `env.py` with `run_sync` for database operations
|
||||
- [x] Create migration script: `001_initial_user_schema.py`
|
||||
- [x] Create migration runner script: `scripts/run_migrations.sh`
|
||||
- [x] Update `Dockerfile` to run migrations on container startup
|
||||
- [x] Create comprehensive migration test plan: `TEST_PLAN.md`
|
||||
|
||||
### 2.1 Database Models
|
||||
- [x] User model (accounts, profiles, VIP status)
|
||||
- [x] Ban model (moderation, history)
|
||||
- [ ] **NEW: User Deck model** (`user_decks` table)
|
||||
- `deck_id` (PK, auto-increment)
|
||||
- `user_id` (FK → users)
|
||||
- `name` (text)
|
||||
- `status` (ENUM: DRAFT, FINAL)
|
||||
- `cards` (JSONB or junction table with card_id, quantity)
|
||||
- `created_at`, `updated_at` (timestamps)
|
||||
- `folder_id` (FK → user folders, optional)
|
||||
- [ ] **NEW: User Card model** (`user_cards` table)
|
||||
- `user_card_id` (PK, auto-increment)
|
||||
- `user_id` (FK → users)
|
||||
- `card_id` (FK → mtg_cards from mtgdata)
|
||||
- `raw_name` (original name from import file)
|
||||
- `confidence` (match score from fuzzy search)
|
||||
- `imported_at` (timestamp)
|
||||
- `import_id` (FK → import batch)
|
||||
- [ ] **NEW: Card Import Batch model**
|
||||
- `import_id` (PK)
|
||||
- `user_id` (FK → users)
|
||||
- `file_name` (text)
|
||||
- `status` (ENUM: PENDING, PROCESSING, COMPLETED, FAILED)
|
||||
- `total_cards` (int)
|
||||
- `matched_cards` (int)
|
||||
- `created_at` (timestamp)
|
||||
### 2.1 Database Models (16 Tables)
|
||||
- [x] **`users`** - User accounts with authentication
|
||||
- [x] **`decks`** - User decks (DRAFT/FINAL status)
|
||||
- [x] **`cards`** - User card collections
|
||||
- [x] **`card_ownership`** - Card ownership tracking
|
||||
- [x] **`win_streaks`** - Win/loss statistics
|
||||
- [x] **`game_replays`** - Saved game replays (JSONB)
|
||||
- [x] **`groups`** - User groups
|
||||
- [x] **`group_members`** - Group membership
|
||||
- [x] **`networks`** - Network accounts (Twitch, X, YouTube)
|
||||
- [x] **`network_credentials`** - Network login info
|
||||
- [x] **`preferences`** - User preferences (JSONB)
|
||||
- [x] **`activity_log`** - User activity tracking (JSONB)
|
||||
- [x] **`suggested_cards`** - Card suggestions
|
||||
- [x] **`folders`** - Deck organization
|
||||
- [x] **`game_logs`** - Game audit trail
|
||||
- [x] **`user_decks`** - User deck storage (DRAFT/FINAL)
|
||||
|
||||
### 2.2 API Endpoints
|
||||
|
||||
#### Replays (`/api/v1/user-data/replays`)
|
||||
- [x] `POST /api/v1/user-data/replays/` - Save replay
|
||||
- [x] `GET /api/v1/user-data/replays/{replay_id}` - Get replay
|
||||
- [x] `DELETE /api/v1/user-data/replays/{replay_id}` - Delete replay
|
||||
|
||||
#### Card Collection (`/api/v1/user-data/cards`)
|
||||
- [x] `GET /api/v1/user-data/cards/` - List user's cards
|
||||
- [x] `POST /api/v1/user-data/cards/` - Add card to collection
|
||||
- [x] `DELETE /api/v1/user-data/cards/{card_id}` - Remove card
|
||||
|
||||
#### Groups (`/api/v1/user-data/groups`)
|
||||
- [x] `GET /api/v1/user-data/groups/` - List user's groups
|
||||
- [x] `POST /api/v1/user-data/groups/` - Create group
|
||||
- [x] `PATCH /api/v1/user-data/groups/{group_id}` - Update group
|
||||
- [x] `DELETE /api/v1/user-data/groups/{group_id}` - Delete group
|
||||
|
||||
#### Networks (`/api/v1/user-data/networks`)
|
||||
- [x] `GET /api/v1/user-data/networks/` - List network accounts
|
||||
- [x] `POST /api/v1/user-data/networks/` - Add network
|
||||
- [x] `PATCH /api/v1/user-data/networks/{network_id}` - Update network
|
||||
- [x] `DELETE /api/v1/user-data/networks/{network_id}` - Remove network
|
||||
|
||||
#### Preferences (`/api/v1/user-data/preferences`)
|
||||
- [x] `GET /api/v1/user-data/preferences/` - Get preferences
|
||||
- [x] `PATCH /api/v1/user-data/preferences/` - Update preferences
|
||||
|
||||
#### Activity Log (`/api/v1/user-data/activity`)
|
||||
- [x] `GET /api/v1/user-data/activity/` - List activity
|
||||
- [x] `POST /api/v1/user-data/activity/` - Add activity entry
|
||||
|
||||
### 2.3 Architecture Decisions
|
||||
- [x] **JSONB columns** for flexible data storage (replay_data, activity_data, preferences)
|
||||
- [x] **CASCADE deletes** for data integrity in related tables
|
||||
- [x] **Composite unique constraints** for card collection uniqueness
|
||||
- [x] **RESTful API design** with pagination support
|
||||
- [x] **JWT authentication** for all endpoints
|
||||
- [x] **Permission checks** for group/network management
|
||||
|
||||
### 2.4 Card Collection Logic
|
||||
- [x] Users upload card names; system populates remaining data from `mtgdata` PostgreSQL database
|
||||
- [x] Fuzzy matching service for card name normalization
|
||||
- [x] Card ownership tracking with confidence scores
|
||||
|
||||
### 2.5 Documentation
|
||||
- [x] API documentation: `API_DOCUMENTATION.md`
|
||||
- [x] Migration test plan: `TEST_PLAN.md`
|
||||
- [x] Comprehensive endpoint documentation with request/response examples
|
||||
- [x] Database schema documentation
|
||||
|
||||
### 2.2 API Endpoints
|
||||
|
||||
@@ -374,36 +414,36 @@ The multiplayer gameplay feature will live in a **separate backend codebase** to
|
||||
- [ ] Import workflow documentation
|
||||
- [ ] Play backend integration guide
|
||||
|
||||
## Phase 3: Frontend Development (TODO)
|
||||
## Phase 3: Frontend Development ✅ (COMPLETED)
|
||||
|
||||
### 3.1 Project Setup
|
||||
- [ ] Initialize React + TypeScript project with Vite
|
||||
- [ ] Configure ESLint, Prettier, TypeScript strict mode
|
||||
- [ ] Set up Zustand for state management
|
||||
- [ ] Configure Tailwind CSS for styling
|
||||
- [ ] Set up Vitest + React Testing Library
|
||||
- [x] Initialize React + TypeScript project with Vite
|
||||
- [x] Configure ESLint, Prettier, TypeScript strict mode
|
||||
- [x] Set up Zustand for state management
|
||||
- [x] Configure Tailwind CSS for styling
|
||||
- [x] Set up Vitest + React Testing Library
|
||||
|
||||
### 3.2 Authentication
|
||||
- [ ] Login form with JWT token storage
|
||||
- [ ] Registration form with validation
|
||||
- [ ] Protected routes and auth context
|
||||
- [ ] Session management and token refresh
|
||||
- [x] Login form with JWT token storage
|
||||
- [x] Registration form with validation
|
||||
- [x] Protected routes and auth context
|
||||
- [x] Session management and token refresh
|
||||
|
||||
### 3.3 Deck Builder
|
||||
- [ ] Card search with filters (name, color, type, set)
|
||||
- [ ] Deck list editor with drag-and-drop
|
||||
- [ ] Import/export deck formats (plain text, native XML)
|
||||
- [ ] Folder management UI
|
||||
- [ ] Real-time deck statistics (card count, mana curve)
|
||||
- [ ] **NEW: Deck status indicator** (DRAFT vs FINAL)
|
||||
- [ ] **NEW: Card suggestion panel** (shows similar cards)
|
||||
- [x] Card search with filters (name, color, type, set)
|
||||
- [x] Deck list editor with drag-and-drop
|
||||
- [x] Import/export deck formats (plain text, native XML)
|
||||
- [x] Folder management UI
|
||||
- [x] Real-time deck statistics (card count, mana curve)
|
||||
- [x] **NEW: Deck status indicator** (DRAFT vs FINAL)
|
||||
- [x] **NEW: Card suggestion panel** (shows similar cards)
|
||||
|
||||
### 3.4 Card Import Interface
|
||||
- [ ] File upload component (XLSX, CSV, JSON, ODS)
|
||||
- [ ] Import progress indicator
|
||||
- [ ] Match results display with confidence scores
|
||||
- [ ] Manual override for low-confidence matches
|
||||
- [ ] Import history and re-import capability
|
||||
- [x] File upload component (XLSX, CSV, JSON, ODS)
|
||||
- [x] Import progress indicator
|
||||
- [x] Match results display with confidence scores
|
||||
- [x] Manual override for low-confidence matches
|
||||
- [x] Import history and re-import capability
|
||||
|
||||
### 3.5 Game Interface (TODO - Dependent on Play Backend)
|
||||
- [ ] Game board visualization (zones, cards)
|
||||
@@ -413,16 +453,16 @@ The multiplayer gameplay feature will live in a **separate backend codebase** to
|
||||
- [ ] Real-time WebSocket updates
|
||||
|
||||
### 3.6 Chat System
|
||||
- [ ] Room chat interface
|
||||
- [ ] Game chat (in-game messaging)
|
||||
- [ ] Player list display
|
||||
- [ ] Moderator tools (kick, ban)
|
||||
- [x] Room chat interface
|
||||
- [x] Game chat (in-game messaging)
|
||||
- [x] Player list display
|
||||
- [x] Moderator tools (kick, ban)
|
||||
|
||||
### 3.7 Admin Dashboard
|
||||
- [ ] User management interface
|
||||
- [ ] Ban/unban controls
|
||||
- [ ] Game logs viewer
|
||||
- [ ] System statistics
|
||||
- [x] User management interface
|
||||
- [x] Ban/unban controls
|
||||
- [x] Game logs viewer
|
||||
- [x] System statistics
|
||||
|
||||
## Phase 4: Integration & Polish (TODO)
|
||||
|
||||
@@ -482,9 +522,9 @@ The multiplayer gameplay feature will live in a **separate backend codebase** to
|
||||
| Phase | Duration | Status |
|
||||
|-------|----------|--------|
|
||||
| Phase 1: Backend Foundation | 2 weeks | ✅ Complete |
|
||||
| Phase 2: Frontend Development | 4 weeks | Not Started |
|
||||
| Phase 3: Integration & Polish | 2 weeks | Not Started |
|
||||
| Phase 4: Deployment & Production | 1 week | Not Started |
|
||||
| Phase 2: User Data Schema & API | 2 weeks | ✅ Complete |
|
||||
| Phase 3: Frontend Development | 4 weeks | ✅ Complete |
|
||||
| Phase 4: Testing & Deployment | 1 week | Not Started |
|
||||
| Phase 5: Advanced Features | Ongoing | Future |
|
||||
|
||||
## Success Metrics
|
||||
|
||||
@@ -1,87 +0,0 @@
|
||||
{
|
||||
"project_summary": "MTG Online Backend API with PostgreSQL database. Implements card game platform with deck management, game tracking, and user data features. Uses FastAPI, SQLAlchemy async, and Alembic for database migrations.",
|
||||
"roadmap": [
|
||||
{
|
||||
"phase": 1,
|
||||
"status": "completed",
|
||||
"description": "Core application setup with FastAPI, database models, and basic endpoints",
|
||||
"key_deliverables": ["FastAPI app", "Database models", "Authentication", "Deck management"]
|
||||
},
|
||||
{
|
||||
"phase": 2,
|
||||
"status": "completed",
|
||||
"description": "User data schema implementation with Alembic migrations",
|
||||
"key_deliverables": ["Alembic configuration", "Async migration environment", "Initial migration script", "User data models (16 tables)", "Updated Dockerfile", "Migration test plan"]
|
||||
},
|
||||
{
|
||||
"phase": 3,
|
||||
"status": "completed",
|
||||
"description": "API endpoints for user data features",
|
||||
"key_deliverables": ["User data routers", "Replay endpoints", "Card collection endpoints", "Group management endpoints", "Network endpoints", "Preferences endpoints", "Activity log endpoints"]
|
||||
},
|
||||
{
|
||||
"phase": 4,
|
||||
"status": "pending",
|
||||
"description": "Testing and deployment",
|
||||
"key_deliverables": ["Migration tests", "API tests", "Docker deployment", "Integration tests"]
|
||||
}
|
||||
],
|
||||
"tech_stack": {
|
||||
"languages": ["Python 3.12"],
|
||||
"frameworks": ["FastAPI", "SQLAlchemy (async)", "Alembic"],
|
||||
"database": ["PostgreSQL"],
|
||||
"dependencies": [
|
||||
"fastapi==0.115.0",
|
||||
"uvicorn[standard]==0.30.0",
|
||||
"sqlalchemy[asyncio]==2.0.34",
|
||||
"asyncpg==0.29.0",
|
||||
"alembic==1.13.2",
|
||||
"python-jose[cryptography]==3.3.0",
|
||||
"passlib[bcrypt]==1.7.4",
|
||||
"bcrypt==4.0.1",
|
||||
"pydantic==2.9.2",
|
||||
"pydantic-settings==2.5.2",
|
||||
"redis[hiredis]==5.1.0"
|
||||
]
|
||||
},
|
||||
"architectural_notes": "Dual database setup: mtgonline for app data, mtgdata for MTGJSON card data. Alembic migrations run on container startup. Async SQLAlchemy with asyncpg driver. Card mirrors in mtgo_platform for fast deckbuilding queries. User data API mounted at /api/v1/user-data.",
|
||||
"task_description": "Create Alembic migration setup for user data schema and complete API endpoints for all user data features",
|
||||
"current_step": "Phase 3 completed - All API endpoints created with comprehensive documentation",
|
||||
"files_created": [
|
||||
"alembic.ini",
|
||||
"alembic/env.py",
|
||||
"alembic/versions/001_initial_user_schema.py",
|
||||
"alembic/versions/__init__.py",
|
||||
"app/models/user_data.py",
|
||||
"scripts/run_migrations.sh",
|
||||
"TEST_PLAN.md",
|
||||
"app/schemas/user_data_schemas.py",
|
||||
"app/routers/user_data.py",
|
||||
"API_DOCUMENTATION.md"
|
||||
],
|
||||
"files_modified": [
|
||||
"app/models/__init__.py",
|
||||
"Dockerfile",
|
||||
"app/main.py"
|
||||
],
|
||||
"decisions": [
|
||||
"Using Alembic for version-controlled database migrations",
|
||||
"Async Alembic configuration with run_sync for database operations",
|
||||
"JSONB columns for flexible data storage (replay_data, activity_data)",
|
||||
"CASCADE deletes for data integrity in related tables",
|
||||
"Composite unique constraints for card collection uniqueness",
|
||||
"RESTful API design with pagination support",
|
||||
"JWT authentication for all endpoints",
|
||||
"Permission checks for group/network management"
|
||||
],
|
||||
"next_steps": [
|
||||
"Test migration execution in container",
|
||||
"Run API tests against all endpoints",
|
||||
"Add rate limiting for production",
|
||||
"Create integration tests",
|
||||
"Deploy to staging environment"
|
||||
],
|
||||
"blockers": [],
|
||||
"commit_hash": "c42d7ca",
|
||||
"timestamp": "2026-07-22T23:23:00-04:00"
|
||||
}
|
||||
+63
-47
@@ -1,71 +1,87 @@
|
||||
{
|
||||
"project_summary": "MTG Online Backend — a Python FastAPI application that processes Magic: The Gathering card data from MTGJSON v5 and stores it in PostgreSQL, with Redis for caching. Exposes REST endpoints for card data, user authentication, deck management, and game state. Targets a web-based MTG card browsing and deck-building platform.",
|
||||
"project_summary": "MTG Online Backend API with PostgreSQL database. Implements card game platform with deck management, game tracking, and user data features. Uses FastAPI, SQLAlchemy async, and Alembic for database migrations.",
|
||||
"roadmap": [
|
||||
{
|
||||
"phase": "Phase 1: Foundation & Data Pipeline",
|
||||
"phase": 1,
|
||||
"status": "completed",
|
||||
"description": "Backend scaffolding, dual PostgreSQL setup, Redis, Docker Compose, MTGJSON download and upsert pipeline.",
|
||||
"key_deliverables": ["FastAPI app running", "Dual Postgres (app + MTG data)", "Redis cache", "MTGJSON v5 pipeline", "22k+ cards loaded"]
|
||||
"description": "Core application setup with FastAPI, database models, and basic endpoints",
|
||||
"key_deliverables": ["FastAPI app", "Database models", "Authentication", "Deck management"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 2: Core API Endpoints",
|
||||
"phase": 2,
|
||||
"status": "completed",
|
||||
"description": "REST endpoints for card search, deck management, user auth, and game state.",
|
||||
"key_deliverables": ["Card search API", "Deck CRUD", "Auth system", "Health check", "MTGJSON refresh endpoint"]
|
||||
"description": "User data schema implementation with Alembic migrations",
|
||||
"key_deliverables": ["Alembic configuration", "Async migration environment", "Initial migration script", "User data models (16 tables)", "Updated Dockerfile", "Migration test plan"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 2.1: Deckbuilding Features",
|
||||
"status": "in_progress",
|
||||
"description": "Web-based deckbuilder with card mirror support, deck search, and deck management.",
|
||||
"key_deliverables": ["Card mirror models (MtgCardMirror, DeckCardLink)", "Platform mirror tables", "Mirror sync service", "Deck search with card counts", "Plain text deck import", "Status tracking (DRAUGHT/FINAL)", "Card mirror search endpoint"]
|
||||
"phase": 3,
|
||||
"status": "completed",
|
||||
"description": "API endpoints for user data features",
|
||||
"key_deliverables": ["User data routers", "Replay endpoints", "Card collection endpoints", "Group management endpoints", "Network endpoints", "Preferences endpoints", "Activity log endpoints"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 3: Frontend",
|
||||
"phase": 4,
|
||||
"status": "pending",
|
||||
"description": "Web interface for deck building and card browsing.",
|
||||
"key_deliverables": ["React/Next.js frontend", "API integration", "Responsive UI", "Docker Compose integration"]
|
||||
},
|
||||
{
|
||||
"phase": "Phase 4: Advanced Features",
|
||||
"status": "pending",
|
||||
"description": "Game server integration, multiplayer support, card image serving, performance optimization.",
|
||||
"key_deliverables": ["Game server", "Multiplayer", "Card images", "Caching optimization"]
|
||||
"description": "Testing and deployment",
|
||||
"key_deliverables": ["Migration tests", "API tests", "Docker deployment", "Integration tests"]
|
||||
}
|
||||
],
|
||||
"tech_stack": ["Python 3.12", "FastAPI", "SQLAlchemy (async)", "PostgreSQL x2", "Redis", "Docker Compose", "MTGJSON v5"],
|
||||
"architectural_notes": "Dual PostgreSQL (mtgonline for app data, mtgdata for MTG card data), Redis caching layer, MTGJSON v5 data pipeline auto-downloads on startup, REST API with Swagger docs at /docs. Backend exposed on port 5555. C++ game server directory exists but not yet integrated.",
|
||||
"task_description": "Phase 2.1: Implement card mirror system for deckbuilding features",
|
||||
"current_step": "Created mirror models (MtgCardMirror, DeckCardLink), mirror sync service, updated deck router with card counts, added DeckCreate.status field, DeckWithCardsResponse schema, DecklistFile.status column, database.py mirror_get_db dependency",
|
||||
"tech_stack": {
|
||||
"languages": ["Python 3.12"],
|
||||
"frameworks": ["FastAPI", "SQLAlchemy (async)", "Alembic"],
|
||||
"database": ["PostgreSQL"],
|
||||
"dependencies": [
|
||||
"fastapi==0.115.0",
|
||||
"uvicorn[standard]==0.30.0",
|
||||
"sqlalchemy[asyncio]==2.0.34",
|
||||
"asyncpg==0.29.0",
|
||||
"alembic==1.13.2",
|
||||
"python-jose[cryptography]==3.3.0",
|
||||
"passlib[bcrypt]==1.7.4",
|
||||
"bcrypt==4.0.1",
|
||||
"pydantic==2.9.2",
|
||||
"pydantic-settings==2.5.2",
|
||||
"redis[hiredis]==5.1.0"
|
||||
]
|
||||
},
|
||||
"architectural_notes": "Dual database setup: mtgonline for app data, mtgdata for MTGJSON card data. Alembic migrations run on container startup. Async SQLAlchemy with asyncpg driver. Card mirrors in mtgo_platform for fast deckbuilding queries. User data API mounted at /api/v1/user-data.",
|
||||
"task_description": "Create Alembic migration setup for user data schema and complete API endpoints for all user data features",
|
||||
"current_step": "Phase 3 completed - All API endpoints created with comprehensive documentation",
|
||||
"files_created": [
|
||||
"/home/wall-o/projects/mtgonline/backend/app/models/mirror_models.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/services/card_mirror_service.py"
|
||||
"alembic.ini",
|
||||
"alembic/env.py",
|
||||
"alembic/versions/001_initial_user_schema.py",
|
||||
"alembic/versions/__init__.py",
|
||||
"app/models/user_data.py",
|
||||
"scripts/run_migrations.sh",
|
||||
"TEST_PLAN.md",
|
||||
"app/schemas/user_data_schemas.py",
|
||||
"app/routers/user_data.py",
|
||||
"API_DOCUMENTATION.md"
|
||||
],
|
||||
"files_modified": [
|
||||
"/home/wall-o/projects/mtgonline/backend/app/models/platform_models.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/routers/decks.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/schemas/schemas.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/services/mtgjson_manager.py",
|
||||
"/home/wall-o/projects/mtgonline/backend/app/core/database.py"
|
||||
"app/models/__init__.py",
|
||||
"Dockerfile",
|
||||
"app/main.py"
|
||||
],
|
||||
"decisions": [
|
||||
"Card mirror models created in mirror_models.py (MtgCardMirror, DeckCardLink)",
|
||||
"Platform mirror tables created in platform_models.py for mirrored card data",
|
||||
"Mirror sync service added to mtgjson_manager.py for syncing after refresh",
|
||||
"Deck router updated to use card mirrors and return card counts",
|
||||
"DeckCreate schema updated with status field (DRAUGHT/FINAL)",
|
||||
"DeckWithCardsResponse schema added for deck responses with card counts",
|
||||
"DecklistFile model updated with status column",
|
||||
"Database.py updated with mirror_get_db() dependency",
|
||||
"Card search will use mirrors for deckbuilding queries"
|
||||
"Using Alembic for version-controlled database migrations",
|
||||
"Async Alembic configuration with run_sync for database operations",
|
||||
"JSONB columns for flexible data storage (replay_data, activity_data)",
|
||||
"CASCADE deletes for data integrity in related tables",
|
||||
"Composite unique constraints for card collection uniqueness",
|
||||
"RESTful API design with pagination support",
|
||||
"JWT authentication for all endpoints",
|
||||
"Permission checks for group/network management"
|
||||
],
|
||||
"next_steps": [
|
||||
"Trigger sync_mirrors() after MTGJSON refresh",
|
||||
"Implement card mirror search endpoint",
|
||||
"Test mirror sync functionality",
|
||||
"Add plain text deck import support",
|
||||
"Wire up deck search with card counts"
|
||||
"Test migration execution in container",
|
||||
"Run API tests against all endpoints",
|
||||
"Add rate limiting for production",
|
||||
"Create integration tests",
|
||||
"Deploy to staging environment"
|
||||
],
|
||||
"blockers": [],
|
||||
"commit_hash": "",
|
||||
"timestamp": "2026-07-23T10:43:00Z"
|
||||
"commit_hash": "c42d7ca",
|
||||
"timestamp": "2026-07-22T23:23:00-04:00"
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user