mtgonline/backend/CODE_STRUCTURE.md

# MTG Online Backend - Code Structure Documentation

## Project Overview

**Location:** `/home/wall-o/projects/mtgonline/backend/`

**Stack:** FastAPI + SQLAlchemy (async) + Alembic + PostgreSQL + Redis

**Purpose:** MTG Online card database management, deck building, user management, and game infrastructure.

---

## 1. Models (`app/models/`)

### 1.1 Core Models (`models.py`)

**User** (`mtgonline_users`)
- `id`: Integer, primary key, indexed
- `username`: String(64), unique, indexed
- `password_hash`: String(128), bcrypt hash
- `salt`: String(128)
- `email`: String(255), indexed
- `country`: String(2)
- `real_name`: String(128)
- `avatar_bmp`: Text (Base64 encoded)
- `privlevel`: String(50), default "User"
- `is_active`: Boolean, default True
- `is_banned`: Boolean, default False
- `ban_reason`: Text
- `ban_ends`: DateTime
- `vip_status`: Integer (0=normal, 1=vip, 2=donator)
- `vip_expiry`: DateTime
- `creation_date`: DateTime, server default now()
- `last_login`: DateTime
- **Relationships:** `decklist_files`, `decklist_folders` (both cascade delete)

**MtonlineCard** (`mtgonline_cards`)
- `id`: Integer, primary key, indexed
- `source_id`: Integer, indexed (references mtg_cards.id in mtgdata)
- `name`: String(255), indexed
- `mana_cost`: String(255)
- `type_line`: String(255)
- `oracle_text`: Text
- `power`: String(50)
- `toughness`: String(50)
- `rarity`: String(50)
- `layout`: String(50)
- `artist`: String(255)
- `flavor_text`: Text
- `numbers`: String(100)
- `identifiers`: Text (JSON string)
- `images`: Text (JSON string)
- `image`: Text (card image URL)
- `set_code`: String(10), indexed
- `set_name`: String(255)
- `card_parts`: Text (comma-separated face names)
- `keywords`: Text (comma-separated)
- `legalities`: Text (JSON of format legality)
- `synced_at`: DateTime, onupdate now()
- `created_at`: DateTime, server default now()

**DecklistFolder** (`mtgonline_decklist_folders`)
- `id`: Integer, primary key, indexed
- `owner_id`: Integer, FK to mtgonline_users.id
- `name`: String(255)
- `parent_id`: Integer, FK to self (recursive)
- `creation_date`: DateTime
- **Relationships:** `owner`, `children` (recursive), `parent`, `files` (cascade delete)

**DecklistFile** (`mtgonline_decklist_files`)
- `id`: Integer, primary key, indexed
- `folder_id`: Integer, FK to mtgonline_decklist_folders.id
- `owner_id`: Integer, FK to mtgonline_users.id
- `name`: String(255)
- `content`: Text (native XML or plain text)
- `format`: String(50), default "native"
- `status`: String(20), default "DRAUGHT"
- `creation_date`: DateTime
- **Relationships:** `folder`, `owner`, `card_links` (added in mirror_models.py)

**Room** (`mtgonline_rooms`)
- `id`: Integer, primary key, indexed
- `name`: String(100), unique
- `description`: Text
- `is_password_protected`: Boolean
- `password_hash`: String(128)
- `creation_date`: DateTime
- **Relationships:** `game_types` (cascade delete)

**RoomGameType** (`mtgonline_rooms_gametypes`)
- `id`: Integer, primary key, indexed
- `room_id`: Integer, FK to mtgonline_rooms.id
- `name`: String(100)
- `description`: Text
- **Relationships:** `room`

**Ban** (`mtgonline_bans`)
- `id`: Integer, primary key, indexed
- `user_id`: Integer, FK to mtgonline_users.id
- `server_id`: Integer
- `reason`: Text
- `moderators`: String(255)
- `ip_address`: String(45)
- `expiration_time`: DateTime
- `active`: Boolean, default True
- `creation_date`: DateTime
- **Relationships:** `user`

**GameLog** (`mtgonline_log`)
- `id`: Integer, primary key, indexed
- `room_id`: Integer, FK to mtgonline_rooms.id
- `player_id`: Integer, FK to mtgonline_users.id
- `message`: Text
- `timestamp`: DateTime
- **Relationships:** `room`, `player`

**AuditLog** (`mtgonline_audit`)
- `id`: Integer, primary key, indexed
- `admin_id`: Integer, FK to mtgonline_users.id
- `action_type`: String(50)
- `target_user_id`: Integer, FK to mtgonline_users.id
- `details`: Text
- `ip_address`: String(45)
- `timestamp`: DateTime
- **Relationships:** `admin`, `target_user`

**Indexes:**
- `idx_decks_owner` on DecklistFile.owner_id
- `idx_decks_folder` on DecklistFile.folder_id
- `idx_bans_active` on Ban.active
- `idx_log_timestamp` on GameLog.timestamp

---

### 1.2 MTG Models (`mtg_models.py`)

**MtgSet** (`mtg_sets`)
- `id`: Integer, primary key, indexed
- `code`: String(10), unique, indexed
- `name`: String(255)
- `type`: String(100)
- `release_date`: DateTime
- `base_set_size`: Integer
- `total_size`: Integer
- `is_foil_only`: Integer
- `is_non_foil_only`: Integer
- `digital`: Integer
- `icon_svg_url`: Text
- `parent_code`: String(10)
- `mtgo_code`: String(10)
- `image`: Text
- `updated_at`: DateTime
- **Relationships:** `cards`

**MtgCard** (`mtg_cards`)
- `id`: Integer, primary key, indexed
- `set_id`: Integer, FK to mtg_sets.id, indexed
- `name`: String(255), indexed
- `mana_cost`: String(255), indexed
- `type_line`: String(255), indexed
- `oracle_text`: Text
- `power`: String(50)
- `toughness`: String(50)
- `rarity`: String(50), indexed
- `layout`: String(50)
- `artist`: String(255)
- `flavor_text`: Text
- `numbers`: String(100)
- `identifiers`: Text (JSON)
- `images`: Text (JSON)
- `image`: Text
- `updated_at`: DateTime
- **Relationships:** `set`

**Indexes:**
- `idx_mtg_cards_name_set` on MtgCard.name, MtgCard.set_id
- `idx_mtg_cards_type` on MtgCard.type_line
- `idx_mtg_cards_rarity` on MtgCard.rarity

---

### 1.3 Mirror Models (`mirror_models.py`)

**MtgCardMirror** (`mtg_cards_mirror`)
- `id`: Integer, primary key, indexed
- `source_id`: Integer, indexed (references mtg_cards.id)
- `name`: String(255), indexed
- `mana_cost`: String(255)
- `type_line`: String(255)
- `oracle_text`: Text
- `power`: String(50)
- `toughness`: String(50)
- `rarity`: String(50)
- `layout`: String(50)
- `artist`: String(255)
- `flavor_text`: Text
- `numbers`: String(100)
- `identifiers`: Text (JSON)
- `images`: Text (JSON)
- `image`: Text
- `card_parts`: Text
- `keywords`: Text
- `legalities`: Text (JSON)
- `set_code`: String(10), indexed
- `set_name`: String(255)
- `synced_at`: DateTime, onupdate now()
- `created_at`: DateTime
- **Relationships:** `deck_links` (cascade delete)

**DeckCardLink** (`deck_card_links`)
- `id`: Integer, primary key, indexed
- `deck_id`: Integer, FK to mtgonline_decklist_files.id, CASCADE delete
- `card_id`: Integer, FK to mtg_cards_mirror.id
- `quantity`: Integer, default 1
- `zone`: String(20), default "main"
- **Constraints:** UniqueConstraint(deck_id, card_id, zone)
- **Indexes:** `idx_deck_card_deck`, `idx_deck_card_card`
- **Relationships:** `deck`, `card`

**Note:** DecklistFile has a back-reference added: `card_links` relationship to DeckCardLink

---

### 1.4 User Data Models (`user_data.py`)

**UserSession** (`user_sessions`)
- `id`: BigInteger, primary key
- `user_id`: Integer, FK to mtgonline_users.id, CASCADE, indexed
- `session_token_hash`: String(255), unique, indexed
- `ip_address`: String(45)
- `user_agent`: Text
- `created_at`: DateTime
- `expires_at`: DateTime
- `is_active`: Boolean, default True
- **Relationships:** `user`

**DeckVersion** (`deck_versions`)
- `id`: BigInteger, primary key
- `deck_id`: Integer, FK to mtgonline_decklist_files.id, CASCADE, indexed
- `version_number`: Integer
- `content`: Text
- `status`: String(20), default "DRAFT"
- `comment`: Text
- `created_at`: DateTime
- **Relationships:** `deck`

**GameReplay** (`game_replays`)
- `id`: BigInteger, primary key
- `game_uuid`: String(36), unique
- `room_id`: Integer, FK to mtgonline_rooms.id, indexed
- `game_type`: String(50)
- `format`: String(50)
- `duration_seconds`: Integer
- `start_time`: DateTime
- `end_time`: DateTime
- `status`: String(20), default "IN_PROGRESS"
- `replay_data`: JSON
- `created_at`: DateTime
- `updated_at`: DateTime
- **Relationships:** `players` (cascade), `outcomes` (cascade)

**ReplayPlayer** (`replay_players`)
- `id`: BigInteger, primary key
- `replay_id`: BigInteger, FK to game_replays.id, CASCADE, indexed
- `user_id`: Integer, FK to mtgonline_users.id, indexed
- `position`: Integer
- `deck_id`: Integer, FK to mtgonline_decklist_files.id
- `won`: Boolean
- `lost`: Boolean
- `concession`: Boolean, default False
- `turn_one`: Boolean, default False
- `created_at`: DateTime
- **Relationships:** `replay`, `user`, `deck`

**GameOutcome** (`game_outcomes`)
- `id`: BigInteger, primary key
- `user_id`: Integer, FK to mtgonline_users.id, indexed
- `game_uuid`: String(36), FK to game_replays.game_uuid, indexed
- `outcome`: String(20), indexed
- `opponent_id`: Integer, FK to mtgonline_users.id
- `format`: String(50)
- `rating_before`: Integer
- `rating_after`: Integer
- `rating_change`: Integer
- `created_at`: DateTime
- **Relationships:** `replay`, `user`, `opponent`

**UserStatistics** (`user_statistics`)
- `user_id`: Integer, FK to mtgonline_users.id, primary key
- `total_games`: Integer, default 0
- `total_wins`: Integer, default 0
- `total_losses`: Integer, default 0
- `total_concessions`: Integer, default 0
- `win_rate`: Float, default 0.0
- `current_streak`: Integer, default 0
- `best_streak`: Integer, default 0
- `average_rating`: Float, default 0.0
- `last_game_date`: DateTime
- `updated_at`: DateTime
- **Relationships:** `user`

**UserCardCollection** (`user_card_collection`)
- `id`: BigInteger, primary key
- `user_id`: Integer, FK to mtgonline_users.id, CASCADE, indexed
- `card_id`: Integer, indexed
- `quantity`: Integer, default 1
- `condition`: String(20), default "NEAR_MINT"
- `language`: String(5), default "EN"
- `is_foil`: Boolean, default False
- `is_alt_art`: Boolean, default False
- `acquired_date`: DateTime
- `acquisition_method`: String(50)
- `notes`: Text
- `created_at`: DateTime
- `updated_at`: DateTime
- **Constraints:** UniqueConstraint(user_id, card_id, is_foil, is_alt_art)
- **Indexes:** `idx_collection_user_card`
- **Relationships:** `user`

**CardWishlist** (`card_wishlist`)
- `id`: BigInteger, primary key
- `user_id`: Integer, FK to mtgonline_users.id, CASCADE
- `card_id`: Integer
- `max_price`: Float
- `notes`: Text
- `created_at`: DateTime
- **Constraints:** UniqueConstraint(user_id, card_id)
- **Relationships:** `user`

**UserGroup** (`user_groups`)
- `id`: BigInteger, primary key
- `name`: String(100)
- `description`: Text
- `owner_id`: Integer, FK to mtgonline_users.id, indexed
- `is_public`: Boolean, default True
- `max_members`: Integer, default 50
- `created_at`: DateTime
- `updated_at`: DateTime
- **Relationships:** `owner`, `members` (cascade), `messages` (cascade)

**GroupMember** (`group_members`)
- `id`: BigInteger, primary key
- `group_id`: BigInteger, FK to user_groups.id, CASCADE, indexed
- `user_id`: Integer, FK to mtgonline_users.id, indexed
- `role`: String(20), default "MEMBER"
- `joined_at`: DateTime
- **Constraints:** UniqueConstraint(group_id, user_id)
- **Relationships:** `group`, `user`

**GroupChatMessage** (`group_chat_messages`)
- `id`: BigInteger, primary key
- `group_id`: BigInteger, FK to user_groups.id, CASCADE, indexed
- `sender_id`: Integer, FK to mtgonline_users.id, indexed
- `message`: Text
- `created_at`: DateTime, indexed
- **Relationships:** `group`, `sender`

**UserNetwork** (`user_networks`)
- `id`: BigInteger, primary key
- `name`: String(100)
- `description`: Text
- `creator_id`: Integer, FK to mtgonline_users.id
- `is_public`: Boolean, default True
- `created_at`: DateTime
- **Relationships:** `creator`, `members` (cascade)

**NetworkMember** (`network_members`)
- `id`: BigInteger, primary key
- `network_id`: BigInteger, FK to user_networks.id, CASCADE, indexed
- `user_id`: Integer, FK to mtgonline_users.id, indexed
- `role`: String(20), default "MEMBER"
- `joined_at`: DateTime
- **Constraints:** UniqueConstraint(network_id, user_id)
- **Relationships:** `network`, `user`

**UserPreference** (`user_preferences`)
- `user_id`: Integer, FK to mtgonline_users.id, primary key
- `theme`: String(20), default "light"
- `notifications_enabled`: Boolean, default True
- `email_notifications`: Boolean, default True
- `auto_save_decks`: Boolean, default True
- `default_format`: String(50), default "standard"
- `language`: String(5), default "EN"
- `updated_at`: DateTime
- **Relationships:** `user`

**UserActivityLog** (`user_activity_log`)
- `id`: BigInteger, primary key
- `user_id`: Integer, FK to mtgonline_users.id, indexed
- `activity_type`: String(50), indexed
- `activity_data`: JSON
- `ip_address`: String(45)
- `created_at`: DateTime, indexed
- **Relationships:** `user`

---

### 1.5 User Deck Models (`user_deck.py`)

**UserDeck** (`user_decks`)
- `id`: BigInteger, primary key, autoincrement
- `user_id`: Integer, FK to mtgonline_users.id, CASCADE, indexed
- `name`: String(255), indexed
- `status`: String(20), default "DRAFT", indexed
- `folder_id`: Integer, FK to mtgonline_decklist_folders.id
- `format`: String(50), default "standard"
- `notes`: Text
- `is_precedent`: Boolean, default False, indexed
- `precedent_name`: String(255)
- `created_at`: DateTime
- `updated_at`: DateTime
- **Relationships:** `user`, `folder`, `cards` (cascade, ordered by id)

**UserDeckCard** (`user_deck_cards`)
- `id`: BigInteger, primary key, autoincrement
- `deck_id`: BigInteger, FK to user_decks.id, CASCADE, indexed
- `card_id`: Integer, FK to mtgonline_cards.id, indexed
- `quantity`: Integer, default 1
- `zone`: String(20), default "main"
- `position`: Integer
- **Constraints:** UniqueConstraint(deck_id, card_id, zone)
- **Indexes:** `idx_deck_cards_deck`, `idx_deck_cards_card`
- **Relationships:** `deck`, `card`

**DeckPrecedent** (`deck_precedents`)
- `id`: BigInteger, primary key, autoincrement
- `name`: String(255), indexed
- `description`: Text
- `format`: String(50), default "standard"
- `is_public`: Boolean, default True, indexed
- `created_by`: Integer, FK to mtgonline_users.id
- `created_at`: DateTime
- `updated_at`: DateTime
- **Relationships:** `creator`, `cards` (cascade)

**DeckPrecedentCard** (`deck_precedent_cards`)
- `id`: BigInteger, primary key, autoincrement
- `precedent_id`: BigInteger, FK to deck_precedents.id, CASCADE, indexed
- `card_id`: Integer, indexed
- `quantity`: Integer, default 1
- `zone`: String(20), default "main"
- **Constraints:** UniqueConstraint(precedent_id, card_id, zone)
- **Relationships:** `precedent`

**CardSuggestion** (`card_suggestions`)
- `id`: BigInteger, primary key, autoincrement
- `deck_id`: BigInteger, FK to user_decks.id, CASCADE, indexed
- `card_id`: Integer, indexed
- `source_card_id`: Integer
- `suggestion_type`: String(50), default "SIMILAR"
- `confidence`: Float
- `notes`: Text
- `created_at`: DateTime
- **Constraints:** UniqueConstraint(deck_id, card_id, source_card_id)
- **Relationships:** `deck`

---

### 1.6 Card Import Models

**CardImportBatch** (`card_import_batches`)
- `id`: Integer, primary key, autoincrement
- `user_id`: Integer, FK to mtgonline_users.id, CASCADE, indexed
- `filename`: String(255)
- `file_type`: String(10) (xlsx, csv, json, ods)
- `file_size`: Integer (bytes)
- `status`: String(20), default "pending", indexed (pending, processing, completed, failed)
- `total_cards`: Integer, default 0
- `matched_cards`: Integer, default 0
- `unmatched_cards`: Integer, default 0
- `match_results`: JSON
- `error_message`: Text
- `created_at`: DateTime
- `updated_at`: DateTime
- **Relationships:** `user`

**UserCardImportRecord** (`user_card_imports_confirmed`)
- `id`: Integer, primary key, autoincrement
- `user_id`: Integer, FK to mtgonline_users.id, CASCADE, indexed
- `batch_id`: Integer, FK to card_import_batches.id, CASCADE, indexed
- `is_confirmed`: Boolean, default True
- `confirmed_at`: DateTime
- **Relationships:** `user`, `batch`

---

## 2. Schemas (`app/schemas/`)

### 2.1 Core Schemas (`schemas.py`)

**Authentication Schemas:**
- `LoginRequest`: username (3-64 chars), password (6-128 chars)
- `LoginResponse`: access_token, refresh_token, token_type="bearer", user (dict)
- `RefreshTokenRequest`: refresh_token
- `TokenResponse`: access_token, token_type="bearer"

**User Schemas:**
- `UserBase`: username, email (optional), country (optional, max 2), real_name (optional)
- `UserCreate`: extends UserBase, password (min 8 chars)
- `UserUpdate`: email, country, real_name, new_password (optional, min 8, max 128)
- `UserResponse`: id, username, email, country, real_name, privlevel, vip_status, is_active, is_banned, ban_reason, creation_date, last_login (from_attributes)

**Deck Schemas:**
- `DeckCreate`: name (1-255 chars), content (min 1), folder_id (optional), format="native" (pattern: native|plain), status="DRAUGHT" (pattern: DRAUGHT|FINAL)
- `DeckUpdate`: name, content, folder_id, status (all optional)
- `DeckResponse`: id, name, content, format, status, folder_id, owner_id, creation_date (from_attributes)
- `FolderCreate`: name (1-255 chars), parent_id (optional)
- `FolderResponse`: id, name, parent_id, owner_id, creation_date (from_attributes)

**Game Schemas:**
- `GameCreate`: room_id, game_type (optional), description (optional), password (optional)
- `GameResponse`: id, room_id, game_type, description, with_password, max_players, player_count, started, creation_date (from_attributes)

**Room Schemas:**
- `RoomResponse`: id, name, description, is_password_protected, game_types (List[str]), player_count, creation_date (from_attributes)

**Ban Schemas:**
- `BanCreate`: user_id, reason (min 1, max 1000), expiration_time (optional)
- `BanResponse`: id, user_id, reason, moderators, expiration_time, active, creation_date (from_attributes)

**Error Schemas:**
- `ErrorResponse`: detail (str)
- `ValidationErrorResponse`: detail (List[dict])

**Pagination Schemas:**
- `PaginationParams`: page (1+, default 1), page_size (1-100, default 50)
- `PaginatedResponse`: items (List[dict]), total, page, page_size, total_pages

**Card Mirror Schemas:**
- `CardMirrorResponse`: id, source_id, name, mana_cost, type_line, oracle_text, power, toughness, rarity, layout, artist, flavor_text, numbers, identifiers, images, image, card_parts, keywords, legalities, set_code, set_name, synced_at, created_at (from_attributes)
- `DeckCardLinkResponse`: id, deck_id, card_id, quantity, zone, card (CardMirrorResponse) (from_attributes)
- `DeckWithCardsResponse`: id, name, content, format, status, folder_id, owner_id, creation_date, card_links (List[DeckCardLinkResponse]) (from_attributes)

---

### 2.2 User Data Schemas (`user_data_schemas.py`)

**Enums:**
- `DeckVersionStatus`: DRAFT, FINAL, ARCHIVED
- `GameReplayStatus`: IN_PROGRESS, COMPLETED, FAILED, CANCELLED
- `GameOutcomeType`: WIN, LOSS, CONCESSION, DISCONNECT
- `GroupMemberRole`: OWNER, ADMIN, MEMBER
- `NetworkMemberRole`: OWNER, ADMIN, MEMBER
- `UserPreferenceTheme`: LIGHT, DARK, SYSTEM
- `ActivityType`: LOGIN, LOGOUT, DECK_EDIT, GAME_PLAYED, CARD_ACQUIRED, CARD_TRADED, GROUP_CREATED, GROUP_JOINED

**Session Schemas:**
- `SessionResponse`: id, user_id, ip_address, user_agent, created_at, expires_at, is_active (from_attributes)
- `SessionCleanupResponse`: cleaned_count, message

**Deck Version Schemas:**
- `DeckVersionCreate`: content (min 1), status=DeckVersionStatus.DRAFT, comment (optional)
- `DeckVersionUpdate`: content, status, comment (all optional)
- `DeckVersionResponse`: id, deck_id, version_number, content, status, comment, created_at (from_attributes)
- `DeckVersionListResponse`: versions (List[DeckVersionResponse]), total

**Game Replay Schemas:**
- `GameReplayCreate`: game_uuid (36 chars), room_id, game_type, format, duration_seconds, start_time, end_time, status=IN_PROGRESS, replay_data (Dict)
- `GameReplayUpdate`: room_id, game_type, format, duration_seconds, end_time, status, replay_data (all optional)
- `GameReplayResponse`: id, game_uuid, room_id, game_type, format, duration_seconds, start_time, end_time, status, replay_data, created_at, updated_at, players (List[Dict]) (from_attributes)
- `GameReplayListResponse`: replays (List[GameReplayResponse]), total, page, page_size, total_pages

**Game Outcome Schemas:**
- `GameOutcomeCreate`: game_uuid, outcome=GameOutcomeType, opponent_id, format, rating_before, rating_after, rating_change
- `GameOutcomeResponse`: id, user_id, game_uuid, outcome, opponent_id, format, rating_before, rating_after, rating_change, created_at (from_attributes)
- `GameOutcomeListResponse`: outcomes (List[GameOutcomeResponse]), total

**User Statistics Schemas:**
- `UserStatisticsResponse`: user_id, total_games, total_wins, total_losses, total_concessions, win_rate, current_streak, best_streak, average_rating, last_game_date, updated_at (from_attributes)
- `StatisticsUpdateResponse`: user_id, total_games, total_wins, total_losses, win_rate, current_streak, updated_at

**Card Collection Schemas:**
- `CardCollectionCreate`: card_id, quantity=1 (ge=1), condition="NEAR_MINT" (max 20), language="EN" (max 5), is_foil=False, is_alt_art=False, acquired_date, acquisition_method, notes
- `CardCollectionUpdate`: quantity, condition, language, is_foil, is_alt_art, acquired_date, acquisition_method, notes (all optional)
- `CardCollectionResponse`: id, user_id, card_id, quantity, condition, language, is_foil, is_alt_art, acquired_date, acquisition_method, notes, created_at, updated_at (from_attributes)
- `CardCollectionListResponse`: cards (List[CardCollectionResponse]), total, page, page_size, total_pages

**Wishlist Schemas:**
- `WishlistCreate`: card_id, max_price, notes
- `WishlistUpdate`: max_price, notes (optional)
- `WishlistResponse`: id, user_id, card_id, max_price, notes, created_at (from_attributes)
- `WishlistListResponse`: items (List[WishlistResponse]), total

**Group Schemas:**
- `GroupCreate`: name (1-100 chars), description, is_public=True, max_members=50 (ge=2, le=500)
- `GroupUpdate`: name, description, is_public, max_members (optional)
- `GroupMemberCreate`: user_id, role=GroupMemberRole.MEMBER
- `GroupMemberUpdate`: role=GroupMemberRole
- `GroupMemberRemove`: user_id
- `GroupResponse`: id, name, description, owner_id, is_public, max_members, created_at, updated_at, member_count=0, is_member=False (from_attributes)
- `GroupListResponse`: groups (List[GroupResponse]), total
- `GroupChatMessageCreate`: message (1-2000 chars)
- `GroupChatMessageResponse`: id, group_id, sender_id, sender_username, message, created_at (from_attributes)
- `GroupChatMessageListResponse`: messages (List[GroupChatMessageResponse]), total, page, page_size, total_pages

**Network Schemas:**
- `NetworkCreate`: name (1-100 chars), description, is_public=True
- `NetworkUpdate`: name, description, is_public (optional)
- `NetworkMemberCreate`: user_id, role=NetworkMemberRole.MEMBER
- `NetworkResponse`: id, name, description, creator_id, is_public, created_at, member_count=0, is_member=False (from_attributes)
- `NetworkListResponse`: networks (List[NetworkResponse]), total

**Preference Schemas:**
- `UserPreferenceUpdate`: theme, notifications_enabled, email_notifications, auto_save_decks, default_format, language (all optional)
- `UserPreferenceResponse`: user_id, theme, notifications_enabled, email_notifications, auto_save_decks, default_format, language, updated_at (from_attributes)

**Activity Log Schemas:**
- `ActivityLogEntry`: id, user_id, activity_type, activity_data, ip_address, created_at (from_attributes)
- `ActivityLogListResponse`: entries (List[ActivityLogEntry]), total, page, page_size, total_pages

**Generic Schemas:**
- `MessageResponse`: message (str)
- `CountResponse`: count (int)
- `ErrorDetail`: error (str), detail (str)

---

### 2.3 User Deck Schemas (`user_deck_schemas.py`)

**Enums:**
- `DeckStatus`: DRAFT, FINAL
- `DeckZone`: MAIN, SIDEBOARD
- `SuggestionType`: SIMILAR, PAIRING, ALTERNATIVE

**Deck Schemas:**
- `UserDeckCreate`: name (1-255 chars), folder_id, format="standard" (max 50), notes, is_precedent=False, precedent_name
- `UserDeckUpdate`: name, folder_id, format, notes, status, is_precedent, precedent_name (all optional)
- `UserDeckResponse`: id, user_id, name, status, folder_id, format, notes, is_precedent, precedent_name, created_at, updated_at, card_count=0, is_owner=False (from_attributes)
- `UserDeckListResponse`: decks (List[UserDeckResponse]), total, page, page_size, total_pages

**Deck Card Schemas:**
- `DeckCardCreate`: card_id, quantity=1 (ge=1), zone=DeckZone.MAIN, position
- `DeckCardUpdate`: quantity, zone, position (optional)
- `DeckCardResponse`: id, deck_id, card_id, quantity, zone, position, created_at (from_attributes)
- `DeckCardWithDetailsResponse`: extends DeckCardResponse, card_name="", card_type_line="", card_image
- `DeckCardListResponse`: cards (List[DeckCardWithDetailsResponse]), total

**Deck Precedent Schemas:**
- `PrecedentCreate`: name (1-255 chars), description, format="standard" (max 50), is_public=True
- `PrecedentUpdate`: name, description, format, is_public (optional)
- `PrecedentResponse`: id, name, description, format, is_public, created_by, created_at, updated_at, card_count=0 (from_attributes)
- `PrecedentListResponse`: precedents (List[PrecedentResponse]), total, page, page_size, total_pages

**Card Suggestion Schemas:**
- `SuggestionCreate`: card_id, source_card_id, suggestion_type=SuggestionType.SIMILAR, confidence (0.0-1.0), notes
- `SuggestionResponse`: id, deck_id, card_id, source_card_id, suggestion_type, confidence, notes, created_at, card_name="" (from_attributes)
- `SuggestionListResponse`: suggestions (List[SuggestionResponse]), total

**Deck Action Schemas:**
- `DeckFinalizeRequest`: status=DeckStatus.FINAL
- `DeckFinalizeResponse`: deck_id, status, message
- `DeckDeleteResponse`: deck_id, message

**Search Schemas:**
- `CardSearchRequest`: query (1-100 chars), limit=50 (1-200), offset=0 (ge=0)
- `CardSearchResponse`: cards (List[Dict]), total, page, page_size, total_pages

**Generic Schemas:**
- `MessageResponse`: message (str)
- `CountResponse`: count (int)

---

### 2.4 Card Import Schemas (`card_import_schemas.py`)

- `CardImportRequest`: card_names (List[str], 1-10000 items)
- `CardImportResponse`: message, card_count, card_names, imported_at
- `CardImportStatusResponse`: has_import, card_count, card_names, last_imported
- `CardMatchResult`: card_id, card_name, matched_name, match_type (exact|fuzzy|partial), confidence (0.0-1.0)
- `CardImportSummary`: total_cards, matched_cards (List[CardMatchResult]), unmatched_cards (List[str]), import_id
- `MessageResponse`: message (str)
- `CountResponse`: count (int)
- `ErrorResponse`: detail (str), error_code

---

### 2.5 Card Search Schemas (`card_search_schemas.py`)

- `CardResponse`: id, name, mana_cost, type_line, oracle_text, power, toughness, rarity, layout, colors, set_code, set_name, identifiers (Dict), images (Dict) (from_attributes)
- `SetResponse`: id, name, code, release_date, card_count (from_attributes)
- `CardTypeResponse`: type (str)
- `CardSearchResponse`: cards (List[Dict]), total, page, page_size, total_pages
- `CardImportResponse`: message, batch_id, card_count, status, imported_at
- `CardImportStatusResponse`: has_import, batch_id, status, card_count, matched_count, unmatched_count, last_imported, error_message
- `CardMatchResult`: card_id, card_name, matched_name, match_type (exact|high_confidence|low_confidence), confidence (0.0-1.0)
- `CardImportSummary`: total_cards, matched_cards (List[CardMatchResult]), unmatched_cards (List[str]), import_id
- `MessageResponse`: message (str)
- `CountResponse`: count (int)
- `ErrorResponse`: detail (str), error_code

---

### 2.6 Protocol Schemas (`proto_messages.py`)

**Base:**
- `ProtoMessageBase`: message_type, timestamp

**Commands:**
- `SessionCommand`: message_type="SessionCommand", cmd_type (int), cmd_id=0, data (Dict)
- `GameCommand`: message_type="GameCommand", cmd_type (int), cmd_id=0, player_id, data (Dict)
- `GameEvent`: message_type="GameEvent", event_type (int), player_id, data (Dict)
- `Response`: message_type="Response", cmd_id, response_code (int), data (Dict)

**Server Info:**
- `ServerInfoUser`: id, name, user_level=0, address, real_name, country, avatar_bmp (bytes), server_id, session_id, accountage_secs, email, privlevel
- `ServerInfoDeckStorageFile`: creation_time
- `ServerInfoDeckStorageFolder`: items (List[Dict])
- `ServerInfoDeckStorageTreeItem`: id, name, file, folder
- `ServerInfoCard`: id, name, x, y, face_down=False, tapped=False, attacking=False, color, pt, annotation, destroy_on_zone_change=False, doesnt_untap=False, counter_list (List[Dict]), attach_player_id, attach_zone, attach_card_id, provider_id
- `ServerInfoZone`: name, zone_type=0, with_coords=False, card_count=0, card_list (List[ServerInfoCard]), always_reveal_top_card=False, always_look_at_top_card=False
- `ServerInfoGame`: server_id, room_id, game_id, description, with_password=False, max_players=4, game_types (List[int]), creator_info, only_buddies=False, only_registered=False, spectators_allowed=False, spectators_need_password=False, spectators_can_chat=False, spectators_omniscient=False, share_decklists_on_load=False, player_count=0, spectators_count=0, started=False, start_time, closed=False

---

### 2.7 Protocol Constants (`protocol_constants.py`)

**Enums:**
- `SessionCommandType` (IntEnum): PING=1000, LOGIN=1001, MESSAGE=1002, LIST_USERS=1003, GET_GAMES_OF_USER=1004, GET_USER_INFO=1005, ADD_TO_LIST=1006, REMOVE_FROM_LIST=1007, DECK_LIST=1008, DECK_NEW_DIR=1009, DECK_DEL_DIR=1010, DECK_DEL=1011, DECK_DOWNLOAD=1012, DECK_UPLOAD=1013, LIST_ROOMS=1014, JOIN_ROOM=1015, REGISTER=1016, ACTIVATE=1017, ACCOUNT_EDIT=1018, ACCOUNT_IMAGE=1019, ACCOUNT_PASSWORD=1020, FORGOT_PASSWORD_REQUEST=1021, FORGOT_PASSWORD_RESET=1022, FORGOT_PASSWORD_CHALLENGE=1023, REQUEST_PASSWORD_SALT=1024, SET_CARD_ART_PARAMS=1025, REPLAY_LIST=1100, REPLAY_DOWNLOAD=1101, REPLAY_MODIFY_MATCH=1102, REPLAY_DELETE_MATCH=1103, REPLAY_GET_CODE=1104, REPLAY_SUBMIT_CODE=1105

- `GameCommandType` (IntEnum): KICK_FROM_GAME=1000, LEAVE_GAME=1001, GAME_SAY=1002, SHUFFLE=1003, MULLIGAN=1004, ROLL_DIE=1005, DRAW_CARDS=1006, UNDO_DRAW=1007, FLIP_CARD=1008, ATTACH_CARD=1009, CREATE_TOKEN=1010, CREATE_ARROW=1011, DELETE_ARROW=1012, SET_CARD_ATTR=1013, SET_CARD_COUNTER=1014, INC_CARD_COUNTER=1015, READY_START=1016, CONCEDE=1017, INC_COUNTER=1018, CREATE_COUNTER=1019, SET_COUNTER=1020, DEL_COUNTER=1021, NEXT_TURN=1022, SET_ACTIVE_PHASE=1023, DUMP_ZONE=1024, REVEAL_CARDS=1026, MOVE_CARD=1027, SET_SIDEBOARD_PLAN=1028, DECK_SELECT=1029, SET_SIDEBOARD_LOCK=1030, CHANGE_ZONE_PROPERTIES=1031, UNCONCEDE=1032, JUDGE=1033, REVERSE_TURN=1034

- `GameEventType` (IntEnum): JOIN=1000, LEAVE=1001, GAME_CLOSED=1002, GAME_HOST_CHANGED=1003, KICKED=1004, GAME_STATE_CHANGED=1005, PLAYER_PROPERTIES_CHANGED=1007, GAME_SAY=1009, CREATE_ARROW=2000, DELETE_ARROW=2001, CREATE_COUNTER=2002, SET_COUNTER=2003, DEL_COUNTER=2004, DRAW_CARDS=2005, REVEAL_CARDS=2006, SHUFFLE=2007, ROLL_DIE=2008, MOVE_CARD=2009, FLIP_CARD=2010, DESTROY_CARD=2011, ATTACH_CARD=2012, CREATE_TOKEN=2013, SET_CARD_ATTR=2014, SET_CARD_COUNTER=2015, SET_ACTIVE_PLAYER=2016, SET_ACTIVE_PHASE=2017, DUMP_ZONE=2018, CHANGE_ZONE_PROPERTIES=2020, REVERSE_TURN=2021, GAME_LOG_NOTICE=2022

- `ResponseCode` (IntEnum): RespNotConnected=-1, RespNothing=0, RespOk=1, RespNotInRoom=2, RespInternalError=3, RespInvalidCommand=4, RespInvalidData=5, RespNameNotFound=6, RespLoginNeeded=7, RespFunctionNotAllowed=8, RespGameNotStarted=9, RespGameFull=10, RespContextError=11, RespWrongPassword=12, RespSpectatorsNotAllowed=13, RespOnlyBuddies=14, RespUserLevelTooLow=15, RespInIgnoreList=16, RespWouldOverwriteOldSession=17, RespChatFlood=18, RespUserIsBanned=19, RespAccessDenied=20, RespUsernameInvalid=21, RespRegistrationRequired=22, RespRegistrationAccepted=23, RespUserAlreadyExists=24, RespEmailRequiredToRegister=25, RespTooManyRequests=26, RespPasswordTooShort=27, RespAccountNotActivated=28, RespRegistrationDisabled=29, RespRegistrationFailed=30, RespActivationAccepted=31, RespActivationFailed=32, RespRegistrationAcceptedNeedsActivation=33, RespClientIdRequired=34, RespClientUpdateRequired=35, RespServerFull=36, RespEmailBlackListed=37

- `ZoneType` (IntEnum): PrivateZone=0, PublicZone=1, HiddenZone=2

- `UserLevelFlag` (IntFlag): IsNothing=0, IsUser=1, IsRegistered=2, IsModerator=4, IsAdmin=8, IsJudge=16

---

### 2.8 User Card Collection Schemas (`user_card_collection.py`)

**Enums:**
- `CardCondition`: NEAR_MINT, LIGHTLY_PLAYED, MODERATELY_PLAYED, HEAVILY_PLAYED, DAMAGED
- `AcquisitionMethod`: PACK_OPENING, TRADE, PURCHASE, GIFT, CONTEST, OTHER

**Card Collection Schemas:**
- `CardCollectionCreate`: card_id, quantity=1 (ge=1), condition=CardCondition.NEAR_MINT, language="EN" (max 5), is_foil=False, is_alt_art=False, acquired_date, acquisition_method, notes
- `CardCollectionUpdate`: quantity, condition, language, is_foil, is_alt_art, acquired_date, acquisition_method, notes (optional)
- `CardCollectionResponse`: id, user_id, card_id, quantity, condition, language, is_foil, is_alt_art, acquired_date, acquisition_method, notes, created_at, updated_at (from_attributes)
- `CardCollectionListResponse`: cards (List[CardCollectionResponse]), total, page, page_size, total_pages

**Wishlist Schemas:**
- `WishlistCreate`: card_id, max_price, notes
- `WishlistUpdate`: max_price, notes (optional)
- `WishlistResponse`: id, user_id, card_id, max_price, notes, created_at (from_attributes)
- `WishlistListResponse`: items (List[WishlistResponse]), total

**Collection Statistics Schemas:**
- `CollectionStatistics`: total_cards, unique_cards, total_quantity, foil_count, alt_art_count, condition_breakdown (Dict), language_breakdown (Dict), acquisition_breakdown (Dict)
- `CollectionSummaryResponse`: statistics (CollectionStatistics), recent_acquisitions (List[CardCollectionResponse]), top_cards (List[CardCollectionResponse])

**Generic Schemas:**
- `MessageResponse`: message (str)
- `CountResponse`: count (int)
- `ErrorDetail`: error (str), detail (str)

---

## 3. Routers (`app/routers/`)

### 3.1 Auth Router (`auth.py`)

**Endpoints:**
- `POST /login` - Authenticate user, return JWT tokens
  - Request: LoginRequest
  - Response: LoginResponse
  - Dependencies: get_db (AsyncSession)
  - Logic: Verify credentials, check account status, generate access/refresh tokens

- `POST /refresh` - Refresh access token
  - Request: RefreshTokenRequest
  - Response: TokenResponse
  - Dependencies: get_db (AsyncSession)
  - Logic: Validate refresh token, verify user still active, generate new access token

- `POST /register` - Register new user
  - Request: UserCreate
  - Response: UserResponse
  - Dependencies: get_db (AsyncSession)
  - Logic: Check username/email uniqueness, hash password, create user

- `GET /me` - Get current authenticated user
  - Query: token (str)
  - Response: UserResponse
  - Dependencies: get_db (AsyncSession)
  - Logic: Decode access token, fetch user

**Imports:**
- From `app.core.security`: verify_password, hash_password, create_access_token, create_refresh_token, decode_token
- From `app.models.models`: User
- From `app.schemas.schemas`: LoginRequest, LoginResponse, RefreshTokenRequest, TokenResponse, UserCreate, UserResponse

---

### 3.2 Users Router (`users.py`)

**Endpoints:**
- `GET /{user_id}` - Get user by ID
  - Response: UserResponse
  - Dependencies: get_db, get_current_user
  - Logic: Fetch user, return response

- `PATCH /{user_id}` - Update user profile
  - Request: UserUpdate
  - Response: UserResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, update fields, hash new password if provided

- `POST /{user_id}/ban` - Ban user (admin only)
  - Query: reason (str), expiration_time (optional str)
  - Response: dict with message
  - Dependencies: get_db, get_current_user
  - Logic: Check admin privileges, update ban status

- `POST /{user_id}/unban` - Unban user (admin only)
  - Response: dict with message
  - Dependencies: get_db, get_current_user
  - Logic: Check admin privileges, clear ban status

**Imports:**
- From `app.core.security`: get_current_user, hash_password
- From `app.models.models`: User
- From `app.schemas.schemas`: UserUpdate, UserResponse

---

### 3.3 Decks Router (`decks.py`)

**Deck CRUD:**
- `GET /` - List user's decks with filtering
  - Query: status_filter, folder_id, is_precedent, page, page_size
  - Response: UserDeckListResponse
  - Dependencies: get_db, get_current_user
  - Logic: Filter decks, count cards, paginate

- `POST /` - Create new user deck (DRAFT)
  - Request: UserDeckCreate
  - Response: UserDeckResponse (201)
  - Dependencies: get_db, get_current_user
  - Logic: Verify folder, create deck

- `GET /{deck_id}` - Get specific deck
  - Response: UserDeckResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, count cards

- `PATCH /{deck_id}` - Update deck
  - Request: UserDeckUpdate
  - Response: UserDeckResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, check not FINAL, update fields

- `DELETE /{deck_id}` - Delete deck
  - Response: MessageResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, delete

**Deck Finalize:**
- `POST /{deck_id}/finalize` - Transition DRAFT to FINAL
  - Response: DeckFinalizeResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, check not already FINAL, verify has cards, update status

**Deck Card Management:**
- `POST /{deck_id}/cards` - Add card to deck
  - Request: DeckCardCreate
  - Response: DeckCardResponse (201)
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, check not FINAL, verify card exists, handle duplicates (update quantity or create new)

- `GET /{deck_id}/cards` - Get all cards in deck
  - Query: zone (optional)
  - Response: DeckCardListResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, fetch cards with details from mirror

- `PATCH /{deck_id}/cards/{card_id}` - Update card in deck
  - Request: DeckCardUpdate
  - Response: DeckCardResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, check not FINAL, update quantity/zone/position

- `DELETE /{deck_id}/cards/{card_id}` - Remove card from deck
  - Response: MessageResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, check not FINAL, delete card entry

**Deck Precedents:**
- `GET /precedents` - List available precedents
  - Query: page, page_size, format_filter
  - Response: PrecedentListResponse
  - Dependencies: get_db, get_current_user
  - Logic: Filter public precedents, count cards, paginate

- `POST /precedents` - Create precedent (template)
  - Request: PrecedentCreate
  - Response: PrecedentResponse (201)
  - Dependencies: get_db, get_current_user
  - Logic: Create precedent with creator

- `GET /precedents/{precedent_id}` - Get specific precedent
  - Response: PrecedentResponse
  - Dependencies: get_db, get_current_user
  - Logic: Fetch precedent, count cards

- `POST /precedents/{precedent_id}/use` - Clone precedent to new deck
  - Response: dict with deck_id, deck_name, card_count
  - Dependencies: get_db, get_current_user
  - Logic: Fetch precedent, create new deck, copy cards

**Card Search:**
- `POST /search/cards` - Search MTG cards
  - Request: CardSearchRequest
  - Response: CardSearchResponse
  - Dependencies: get_db, get_current_user
  - Logic: Search local mirror by name/type_line/mana_cost with ILIKE

**Card Suggestions:**
- `GET /{deck_id}/suggestions` - Get card suggestions
  - Query: suggestion_type (optional)
  - Response: SuggestionListResponse
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, fetch suggestions with card names

- `POST /{deck_id}/suggestions` - Add suggestion
  - Request: SuggestionCreate
  - Response: SuggestionResponse (201)
  - Dependencies: get_db, get_current_user
  - Logic: Verify ownership, check not FINAL, create suggestion

**Imports:**
- From `app.core.database`: get_db, mtg_get_db
- From `app.core.security`: get_current_user
- From `app.models.models`: User, DecklistFolder, MtgonlineCard
- From `app.models.mtg_models`: MtgCard, MtgSet
- From `app.models.user_deck`: UserDeck, UserDeckCard, DeckPrecedent, DeckPrecedentCard, CardSuggestion
- From `app.schemas.user_deck_schemas`: All deck-related schemas

---

### 3.4 Other Routers

**Rooms Router (`rooms.py`)**
- File exists but content not fully read

**Games Router (`games/`)**
- Directory exists (sub-routers)

**Admin Router (`admin.py`)**
- File exists but content not fully read

**Card Router (`card_router.py`)**
- File exists but content not fully read

**Interactions Router (`interactions.py`)**
- File exists but content not fully read

**Refresh Router (`refresh.py`)**
- File exists but content not fully read

**Card Import Router (`card_import.py`)**
- File exists but content not fully read

**Users Router (`users.py`)**
- Already documented above

**WS Router (`ws.py`)**
- File exists but content not fully read

---

## 4. Services (`app/services/`)

### 4.1 Card Database Service (`card_database.py`)
- File exists but content not fully read

### 4.2 Card Mirror Service (`card_mirror_service.py`)
- File exists but content not fully read

### 4.3 Card Search Service (`card_search_service.py`)
- File exists but content not fully read

### 4.4 Deck Manager Service (`deck_manager.py`)
- File exists but content not fully read

### 4.5 Deck Parser Service (`deck_parser.py`)
- File exists but content not fully read

### 4.6 Deck Suggestion Service (`deck_suggestion_service.py`)
- File exists but content not fully read

### 4.7 File Parser Service (`file_parser.py`)
- File exists but content not fully read

### 4.8 Fuzzy Card Matcher Service (`fuzzy_card_matcher.py`)
- File exists but content not fully read

### 4.9 Game Server Service (`game_server.py`)
- File exists but content not fully read

### 4.10 Import Batch Processor Service (`import_batch_processor.py`)
- File exists but content not fully read

### 4.11 MTGJSON Downloader Service (`mtgjson_downloader.py`)
- File exists but content not fully read

### 4.12 MTGJSON Loader Service (`mtgjson_loader.py`)
- File exists but content not fully read

### 4.13 MTGJSON Manager Service (`mtgjson_manager.py`)
- File exists but content not fully read

### 4.14 MTGJSON Uploader Service (`mtgjson_uploader.py`)
- File exists but content not fully read

---

## 5. Core Configuration (`app/core/`)

### 5.1 Database (`database.py`)
- File exists but content not fully read

### 5.2 Redis Client (`redis_client.py`)
- File exists but content not fully read

### 5.3 Security (`security.py`)
- File exists but content not fully read

### 5.4 Settings (`settings.py`)
- File exists but content not fully read

---

## 6. Main Application (`app/main.py`)

- File exists but content not fully read

---

## 7. Alembic Migrations (`alembic/`)

- Migration directory exists
- Migration files present but not fully documented

---

## 8. Test Structure (`tests/`)

- Test directory exists
- Test files present but not fully documented

---

## Summary

The MTG Online backend is a comprehensive FastAPI application with:

**Data Layer:**
- 20+ SQLAlchemy models across 6 model files
- Core user/deck/room management
- MTG card database integration (mtgjson.com)
- Card mirroring for performance
- User deck building with precedents
- Game replay and statistics
- Social features (groups, networks)
- Card collection and wishlist

**API Layer:**
- 3+ fully documented routers (auth, users, decks)
- 7+ additional routers (rooms, games, admin, card_router, interactions, refresh, card_import, ws)
- Comprehensive Pydantic schemas (8 schema files)
- Protocol buffer message definitions
- Protocol constants for MTG Online client

**Service Layer:**
- 14 service files for business logic
- Card database management
- Deck parsing and management
- Card search and fuzzy matching
- MTGJSON data loading and synchronization
- File import processing

**Infrastructure:**
- Async SQLAlchemy with PostgreSQL
- Redis for caching/sessions
- JWT authentication
- Alembic migrations
- Docker deployment

**Note:** This documentation covers the structure that was explicitly read. Several files (services, core configs, additional routers) exist but their detailed contents were not fully read in this session.