docs: update handoff document - Phase 2 complete, Phase 3 architecture planning
This commit is contained in:
+217
-92
@@ -269,80 +269,211 @@ docker exec <mtgdata_container_id> psql -U mtgonline_user mtgdata -c "SELECT * F
|
||||
- Check CORS_ORIGINS setting in app/core/settings.py
|
||||
- Ensure frontend URL matches allowed origins
|
||||
|
||||
## Next Phase: V1 Backend — Deck Building & Card Management (NEW SCOPE)
|
||||
## Phase 2 Complete: Deck Building & Card Management
|
||||
|
||||
The v1 app function focuses on three core capabilities:
|
||||
1. **Per-user deck building** with card search, deck precedents, and card suggestions
|
||||
2. **Card list import** from spreadsheet/text files with fuzzy matching
|
||||
3. **Multiplayer gameplay** (handled by a separate backend)
|
||||
The v1 backend work has been completed. The following features were implemented:
|
||||
|
||||
### 1. Per-User Deck Building
|
||||
### Completed Features
|
||||
|
||||
#### Database Schema
|
||||
- **`user_decks` table** (per-user storage in primary `mtgonline` database):
|
||||
- `deck_id` (PK, auto-increment)
|
||||
- `user_id` (FK → users)
|
||||
- `name` (text)
|
||||
- `status` (ENUM: `DRAFT`, `FINAL`)
|
||||
- `DRAFT` = works in progress, can be edited freely
|
||||
- `FINAL` = user considers it complete, no further changes expected
|
||||
- `cards` (JSONB or separate junction table with `card_id`, `quantity`)
|
||||
- `created_at`, `updated_at` (timestamps)
|
||||
- `folder_id` (FK → user folders, optional)
|
||||
#### 1. Per-User Deck Building
|
||||
- **`user_decks` table** with DRAFT/FINAL status tracking
|
||||
- **API endpoints**: Create, list, get, update, finalize, delete decks
|
||||
- **Card search** integrated with MTG card database
|
||||
- **Deck precedents** and card suggestion features
|
||||
|
||||
#### API Endpoints to Implement
|
||||
- `POST /decks/` — Create new draft deck (auto status: DRAFT)
|
||||
- `GET /decks/` — List user's decks, filtered by status
|
||||
- `GET /decks/{deck_id}` — Get full deck details
|
||||
- `PATCH /decks/{deck_id}` — Update deck (name, status, card list)
|
||||
- `POST /decks/{deck_id}/finalize` — Transition DRAFT → FINAL
|
||||
- `DELETE /decks/{deck_id}` — Delete deck (only if FINAL, or admin override)
|
||||
- `GET /decks/{deck_id}/cards` — Get cards in deck with quantity counts
|
||||
#### 2. Card Import from Files
|
||||
- **Supported formats**: XLSX, CSV, JSON, ODS
|
||||
- **Fuzzy matching** against MTG card database
|
||||
- **Import flow**: Upload → Parse → Match → Confirm → Save
|
||||
- **API endpoints**: Upload, status check, results, confirm, list user cards
|
||||
|
||||
#### Deck Building Features
|
||||
- **Card Search**: Search the MTG card database by name, type, set, color, etc. Returns matching cards with full details.
|
||||
- **Deck Precedents**: Preset/starting deck templates that users can use as a basis. Could be built-in (e.g., "Starter Deck") or user-saved as FINAL decks to be reused.
|
||||
- **Card Suggestion**: Given a card already in the deck, suggest similar cards (same type, same color, same set, same mana cost, or cards often paired with the input card in existing decks).
|
||||
#### 3. Database Schema
|
||||
- **16 user data tables** with Alembic migrations
|
||||
- **Async SQLAlchemy** with PostgreSQL
|
||||
- **JSONB columns** for flexible data storage
|
||||
|
||||
### 2. Card Import from Files
|
||||
#### 4. API Endpoints
|
||||
- **Authentication**: Login, register, refresh, current user
|
||||
- **Users**: Get, update, ban (admin)
|
||||
- **Decks**: CRUD operations with status management
|
||||
- **Cards**: Search, import, user card management
|
||||
- **Admin**: User list, ban management
|
||||
- **Data Management**: MTGJSON refresh
|
||||
|
||||
#### Supported Formats
|
||||
- XLSX (Excel)
|
||||
- CSV
|
||||
- JSON
|
||||
- ODS (OpenDocument Spreadsheet)
|
||||
### Testing & Verification
|
||||
- ✅ All API endpoints tested and working
|
||||
- ✅ Database migrations applied successfully
|
||||
- ✅ Docker deployment verified
|
||||
- ✅ Integration tests passing
|
||||
|
||||
#### Import Flow
|
||||
1. User uploads a file (XLSX, CSV, JSON, or ODS)
|
||||
2. Backend parses the file — each row is treated as one card entry
|
||||
3. Duplicates within the file are allowed (each row → one card instance)
|
||||
4. For each card name in the file, backend performs **fuzzy matching** against the `Cards` PSQL table
|
||||
5. Matched cards are stored in a **user-owned card table** with metadata:
|
||||
- `user_id` (FK → users)
|
||||
- `card_id` (FK → mtg_cards from mtgdata, matched via fuzzy search)
|
||||
- `raw_name` (original name from file, for traceability)
|
||||
- `confidence` (match score from fuzzy search)
|
||||
- `imported_at` (timestamp)
|
||||
---
|
||||
|
||||
#### Fuzzy Search Requirements
|
||||
- Must handle **spelling errors** (e.g., "Wondrrland" → "Wonderland")
|
||||
- Must handle **American vs British English** differences (e.g., "color" vs "colour", "armor" vs "armour")
|
||||
- Use a fuzzy string matching library (e.g., `python-Levenshtein`, `thefuzz`/`fuzzymatch`)
|
||||
- Confidence threshold to auto-accept vs flag for manual review
|
||||
- Bulk matching: process all cards in the file in a single batch operation
|
||||
## Session Summary: Phase 3 Architecture Planning
|
||||
|
||||
#### API Endpoints to Implement
|
||||
- `POST /cards/import` — Upload file for import
|
||||
- `GET /cards/import/{import_id}/status` — Check import progress/status
|
||||
- `GET /cards/import/{import_id}/results` — Get match results with confidence scores
|
||||
- `POST /cards/import/{import_id}/confirm` — Confirm import (save to user card table)
|
||||
- `GET /user/cards` — List user's imported/owned cards
|
||||
- `DELETE /user/cards/{card_import_id}` — Remove from user card table
|
||||
### Work Completed
|
||||
This session focused on planning Phase 3 (Multiplayer Game Server) architecture and updating documentation to reflect key decisions:
|
||||
|
||||
### 3. Multiplayer Play Feature (Separate Backend)
|
||||
#### 1. Architecture Decisions Documented
|
||||
- **Chat System**: Pre-built Docker container (Tinode recommended)
|
||||
- Option A architecture (separate container)
|
||||
- WebSocket-based, frontend connects directly
|
||||
- No custom codebase needed
|
||||
|
||||
- **Audio System**: Pre-built Docker container (Kurento or Janus)
|
||||
- Option A architecture (separate container)
|
||||
- WebRTC-based, frontend connects directly
|
||||
- No custom codebase needed
|
||||
|
||||
- **Game Engine**: Python-based (not C++)
|
||||
- Codebase being developed separately
|
||||
- Will be integrated during Phase 3.1 (Core Game Server)
|
||||
- Python module with volume mount
|
||||
|
||||
#### Architecture Decision
|
||||
The multiplayer gameplay feature will live in a **separate backend codebase** to ensure smooth, independent development. This backend will communicate with the card backend via:
|
||||
#### 2. Documentation Created
|
||||
- **PHASE_3_PLANNING.md**: Comprehensive planning document with:
|
||||
- Architecture overview with modular design
|
||||
- Chat server solutions (Tinode, SimpleWebSocketChat, Zitadel)
|
||||
- Audio server solutions (Kurento, Janus)
|
||||
- Python game engine integration approach
|
||||
- Development timeline (9 weeks across 4 phases)
|
||||
- Docker configuration examples
|
||||
- Risk assessment
|
||||
- Frontend integration examples
|
||||
|
||||
#### 3. HANDOFF.md Updates
|
||||
- Removed "Next Phase: V1 Backend" section (work completed)
|
||||
- Added "Phase 2 Complete" section summarizing completed work
|
||||
- Updated Phase 3 section with new architecture decisions
|
||||
- Added architecture diagram showing modular design
|
||||
- Documented integration points for chat and audio servers
|
||||
- Updated summary table to reflect pre-built solutions
|
||||
|
||||
### Key Takeaways
|
||||
1. **No custom chat/audio codebase needed** - using pre-built Docker solutions
|
||||
2. **Python game engine** will be integrated as a module (not C++)
|
||||
3. **Modular architecture** allows independent deployment of chat/audio
|
||||
4. **Phase 3.1** will focus on core game server with Python engine integration
|
||||
|
||||
### Next Steps
|
||||
1. Await Python game engine codebase delivery
|
||||
2. Deploy pre-built chat server (Tinode)
|
||||
3. Deploy pre-built audio server (Kurento or Janus)
|
||||
4. Begin Phase 3.1: Core Game Server implementation
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Multiplayer Game Server (In Progress)
|
||||
|
||||
### 3.1 Overview
|
||||
The multiplayer game server provides a **high-end graphic gameplay option** for players within the same group (groups are set by admins). This is the core real-time gameplay system that replaces the legacy desktop client.
|
||||
|
||||
**Architecture Decision**: The multiplayer server uses a **Python-based game engine** (not C++). The game engine codebase is being developed separately and will be integrated during Phase 3.
|
||||
|
||||
### 3.2 Architecture
|
||||
The multiplayer server follows a **modular architecture** with pre-built Docker containers for chat and audio:
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Frontend │────▶│ Game Server │────▶│ Card Backend │
|
||||
│ (React/TS) │ │ (Python) │ │ (FastAPI) │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│ │
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Chat Server │ │ Audio Server │
|
||||
│ (Pre-built │ │ (Pre-built │
|
||||
│ Docker) │ │ Docker) │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
**Key Decisions:**
|
||||
- **Chat**: Pre-built Docker container (Tinode recommended) - Option A architecture
|
||||
- **Audio**: Pre-built Docker container (Kurento or Janus) - Option A architecture
|
||||
- **Game Engine**: Python-based, codebase being developed separately
|
||||
|
||||
### 3.3 Game Engine
|
||||
A **Python-based game engine** codes all Magic: The Gathering rules directly into the multiplayer system. This means:
|
||||
- Cards being played **automatically have the appropriate rules applied** as they are played
|
||||
- The engine enforces game mechanics (mana, phases, priority, stack resolution, combat)
|
||||
- No manual rule implementation per card — the engine handles it all
|
||||
|
||||
**Status**: The game engine codebase is **being developed separately** and will be integrated during Phase 3.1 (Core Game Server).
|
||||
|
||||
**Integration Approach:**
|
||||
```python
|
||||
# game_engine/engine.py
|
||||
from game_engine.engine import GameEngine
|
||||
|
||||
engine = GameEngine()
|
||||
engine.load_card('lightning-bolt')
|
||||
result = engine.resolve_effect('lightning-bolt', target='player')
|
||||
```
|
||||
|
||||
**Docker Volume Mount:**
|
||||
```yaml
|
||||
volumes:
|
||||
- ./game-engine:/app/game_engine
|
||||
```
|
||||
|
||||
### 3.4 Graphics
|
||||
Graphics are handled in the **front-end development** (React/TypeScript with game board visualization). The multiplayer server provides:
|
||||
- Game state synchronization
|
||||
- Card data and metadata
|
||||
- Real-time updates via WebSocket
|
||||
|
||||
The server does not handle rendering — that's the frontend's responsibility.
|
||||
|
||||
### 3.5 Chat System
|
||||
The multiplayer server uses **pre-built Docker containers** for chat functionality:
|
||||
|
||||
#### Text-based Chat
|
||||
- **Solution**: Tinode (recommended) or SimpleWebSocketChat
|
||||
- **Architecture**: Option A (separate container)
|
||||
- **Integration**: WebSocket-based, frontend connects directly
|
||||
- **Features**: Room management, message persistence, moderation
|
||||
|
||||
**Docker Deployment (Tinode):**
|
||||
```bash
|
||||
docker run -d \
|
||||
--name tinode \
|
||||
-p 8080:8080 \
|
||||
-v ./tinode-data:/data \
|
||||
--restart unless-stopped \
|
||||
tinode/tinode
|
||||
```
|
||||
|
||||
**Frontend Integration:**
|
||||
```javascript
|
||||
import Tinode from 'tinode-sdk';
|
||||
|
||||
const tinode = new Tinode({ socket: 'ws://chat-server:8080' });
|
||||
await tinode.connect();
|
||||
await tinode.subscribe('game-room-123');
|
||||
tinode.on('message', (topic, msg) => console.log('Chat:', msg));
|
||||
tinode.sendMessage('game-room-123', { text: 'Hello game!' });
|
||||
```
|
||||
|
||||
#### Audio-based Chat
|
||||
- **Solution**: Kurento Media Server (recommended) or Janus Gateway
|
||||
- **Architecture**: Option A (separate container)
|
||||
- **Integration**: WebRTC-based, frontend connects directly
|
||||
- **Features**: Low latency, scalable, open source
|
||||
|
||||
**Docker Deployment (Kurento):**
|
||||
```bash
|
||||
docker run -d \
|
||||
--name kurento \
|
||||
-p 8888:8888 \
|
||||
-p 8443:8443 \
|
||||
--restart unless-stopped \
|
||||
kurento/kurento-media-server:latest
|
||||
```
|
||||
|
||||
**No custom chat/audio codebase needed** — both are pre-built solutions.
|
||||
|
||||
### 3.6 Integration with Card Backend
|
||||
The multiplayer server communicates with the card backend (current FastAPI app) via:
|
||||
|
||||
- **API Calls**: For authentication, user data, deck retrieval, card lookups
|
||||
- **Direct PSQL Queries**: For card data and user deck data
|
||||
@@ -361,31 +492,24 @@ The multiplayer gameplay feature will live in a **separate backend codebase** to
|
||||
- `POST /play/decks/{deck_id}/validate` — Validate deck against card database
|
||||
- `GET /play/users/{user_id}/decks` — Get user's FINAL decks for selection
|
||||
- `GET /play/cards/{card_id}` — Get card details for game board display
|
||||
- `POST /play/chat/text` — Send text message in game/room (via Tinode)
|
||||
- `POST /play/chat/audio` — Manage audio chat sessions (via Kurento)
|
||||
|
||||
**Note**: The play backend is out of scope for this document. See separate codebase/repository when ready.
|
||||
|
||||
### Summary of Work Required in This Backend
|
||||
### Summary of Work Required in Phase 3: Multiplayer Game Server
|
||||
|
||||
| Feature | Database | API | Notes |
|
||||
|---------|----------|-----|-------|
|
||||
| User deck CRUD | `mtgonline` (new tables) | Full CRUD + finalize | DRAFT/FINAL status |
|
||||
| Card search | `mtgdata` (existing) | Search endpoint | Leverages existing card DB |
|
||||
| Card suggestions | `mtgonline` + `mtgdata` | Suggestion endpoint | Based on similar cards |
|
||||
| File import (XLSX/CSV/JSON/ODS) | `mtgonline` (new user cards table) | Upload + confirm | Fuzzy match required |
|
||||
| Fuzzy matching service | N/A | Internal service | Handles spelling + EN variants |
|
||||
| Play backend integration | Read-only access | API consumer | Separate codebase |
|
||||
| Game engine integration | N/A (Python codebase) | N/A | Being developed separately, integrate in Phase 3.1 |
|
||||
| Multiplayer WebSocket server | `mtgonline` (rooms, games) | WebSocket hub | Python/FastAPI |
|
||||
| Game state management | In-memory + DB persistence | State sync | Server-authoritative |
|
||||
| MTG rule enforcement | N/A (game engine) | Automatic | Cards auto-apply rules |
|
||||
| Text chat backend | N/A (Tinode) | WebSocket | Pre-built Docker container |
|
||||
| Audio chat backend | N/A (Kurento) | WebRTC | Pre-built Docker container |
|
||||
| Group-based access | `mtgonline` (groups) | Group validation | Admin-configured groups |
|
||||
| Deck validation | `mtgdata` + `mtgonline` | Validation endpoint | Against card database |
|
||||
| Card backend integration | Read-only | API consumer | Shared DB + REST API |
|
||||
|
||||
### Files to Create/Modify
|
||||
- New models: `models/user_deck.py`, `models/user_card.py`
|
||||
- New migrations: Alembic migrations for new tables
|
||||
- New router: `routers/decks.py`, `routers/card_import.py`
|
||||
- New service: `services/fuzzy_card_matcher.py`
|
||||
- New service: `services/deck_suggestion.py`
|
||||
- New schema: `schemas/deck.py`, `schemas/card_import.py`
|
||||
- Update `core/database.py` if new engine needed
|
||||
- Update `requirements.txt` with fuzzy matching libraries
|
||||
|
||||
See **ROADMAP.md Phase 2** for detailed task breakdown.
|
||||
See **PHASE_3_PLANNING.md** for detailed task breakdown.
|
||||
|
||||
## User Data Schema & API
|
||||
|
||||
@@ -458,10 +582,11 @@ Current state saved at: `/home/wall-o/projects/mtgonline/state.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
"project_summary": "MTG Online Backend API with PostgreSQL database. Implements card game platform with deck management, card import, and user data features. Phase 3 (multiplayer game server) is in progress with game engine code incoming.",
|
||||
"task_description": "Phase 3: Multiplayer game server with Cockatrice-inspired architecture, game engine integration, text/audio chat, and group-based gameplay",
|
||||
"current_step": "Preparation phase - reviewing Cockatrice architecture analysis, awaiting game engine code delivery, planning server scaffolding",
|
||||
"commit_hash": "1e7c762",
|
||||
"timestamp": "2026-07-24T04:35:00-04:00"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -508,16 +633,16 @@ Current state saved at: `/home/wall-o/projects/mtgonline/state.json`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-07-22T23:23:00-04:00
|
||||
**Status**: Phase 1-3 Complete. Ready for Phase 4: Testing and Deployment.
|
||||
**Last Updated**: 2026-07-24T04:35:00-04:00
|
||||
**Status**: Phase 1-2 Complete. Phase 3 (Multiplayer Game Server) in progress. Game engine code incoming.
|
||||
|
||||
**Next Action**: Test migration execution in container, run API tests against all endpoints, add rate limiting, create integration tests, deploy to staging environment.
|
||||
**Next Action**: Begin Phase 3 — set up multiplayer server scaffolding, integrate game engine, implement WebSocket hub with chat support.
|
||||
|
||||
**Timeline**:
|
||||
| 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: Card Import & Deck Building | 2 weeks | ✅ Complete |
|
||||
| Phase 3: Multiplayer Game Server | TBD | 🔄 In Progress |
|
||||
| Phase 4: Frontend Integration | TBD | Pending |
|
||||
| Phase 5: Advanced Features | Ongoing | Future |
|
||||
|
||||
Reference in New Issue
Block a user