# pier-tmp/mtgda architecture

> Architecture diagram of the GitHub repository pier-tmp/mtgda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pier-tmp/mtgda
- Repository: https://github.com/pier-tmp/mtgda
- Video tour (about a minute): https://gitdiagram.com/pier-tmp/mtgda/video

## Overview

MTG Draft Assistant turns a current booster pack and prior picks into ranked card recommendations. The API resolves catalog names or custom card dictionaries, batches uncached card encoding, builds draft-history inputs, and asks a Torch or ONNX backend to score candidates; the API converts scores to probabilities and rankings. Stateful drafting records each selected card for the next step. The README documents zero-shot support for unseen cards. Backend and model wiring is supported by sampled source; the catalog contents and deployment assets were not sampled.

Main entry points: [`src/mtgda/backend.py`](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/backend.py) (Inference backends), [`src/mtgda/api.py`](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py) (Assistant API), [`src/mtgda/model.py`](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py) (Card encoder), [`src/mtgda/features.py`](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/features.py) (Card featurizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Draft API"]
  node_assistant["Assistant API<br/>[api.py]"]
  node_draft["Stateful draft<br/>[api.py]"]
  node_recommendations["Ranked recommendations<br/>[api.py]"]
end

subgraph group_cards["Card Resolution"]
  node_database[("Card database<br/>[cards.py]")]
  node_featurizer["Card featurizer<br/>[features.py]"]
  node_patterns["Mechanic patterns"]
end

subgraph group_inference["Inference"]
  node_backend["Inference backends<br/>[backend.py]"]
  node_tokenizer["Text tokenizer"]
  node_network["Draft network<br/>[model.py]"]
  node_cardencoder["Card encoder<br/>[model.py]"]
  node_draftmodel["Draft scorer<br/>[model.py]"]
end

subgraph group_artifacts["Model Artifacts"]
  node_checkpoint["Checkpoint loader<br/>[checkpoint.py]"]
  node_hub["Model hub"]
  node_textmodel["Pretrained text model"]
end

node_drafter(("Drafting consumer"))

node_drafter -->|"requests ranking"| node_assistant
node_assistant -->|"resolves cards"| node_database
node_assistant -->|"encodes uncached cards"| node_backend
node_backend -->|"extracts features"| node_featurizer
node_featurizer -->|"loads patterns"| node_patterns
node_backend -->|"tokenizes text"| node_tokenizer
node_backend -->|"encodes cards"| node_cardencoder
node_cardencoder -->|"encodes text"| node_textmodel
node_assistant -->|"scores draft inputs"| node_backend
node_backend -->|"scores candidates"| node_draftmodel
node_network -->|"contains"| node_cardencoder
node_network -->|"contains"| node_draftmodel
node_draft -->|"ranks current pack"| node_assistant
node_draft -->|"validates pick"| node_database
node_assistant -->|"returns ranking"| node_recommendations
node_recommendations -->|"presents choices"| node_drafter
node_backend -->|"loads weights"| node_checkpoint
node_backend -.->|"downloads artifacts"| node_hub
node_hub -.->|"provides model files"| node_backend
node_tokenizer -.->|"loads tokenizer"| node_hub
node_checkpoint -.->|"loads pretrained weights"| node_textmodel

click node_assistant "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py"
click node_draft "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py"
click node_recommendations "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py"
click node_database "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/cards.py"
click node_featurizer "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/features.py"
click node_patterns "https://github.com/pier-tmp/mtgda/tree/main/src/mtgda/assets/patterns"
click node_backend "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/backend.py"
click node_network "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py"
click node_cardencoder "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py"
click node_draftmodel "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py"
click node_checkpoint "https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/checkpoint.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_assistant,node_draft,node_recommendations toneBlue
class node_database,node_featurizer,node_patterns toneAmber
class node_backend,node_tokenizer,node_network,node_cardencoder,node_draftmodel toneMint
class node_checkpoint,node_hub,node_textmodel toneRose
class node_drafter toneIndigo
```

## Components

### Draft API

- [Assistant API](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py): `src/mtgda/api.py`
- [Stateful draft](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py): `src/mtgda/api.py`
- [Ranked recommendations](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/api.py): `src/mtgda/api.py`

### Card Resolution

- [Card database](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/cards.py): `src/mtgda/cards.py`
- [Card featurizer](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/features.py): `src/mtgda/features.py`
- [Mechanic patterns](https://github.com/pier-tmp/mtgda/tree/main/src/mtgda/assets/patterns): `src/mtgda/assets/patterns`

### Inference

- [Inference backends](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/backend.py): `src/mtgda/backend.py`
- **Text tokenizer**
- [Draft network](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py): `src/mtgda/model.py`
- [Card encoder](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py): `src/mtgda/model.py`
- [Draft scorer](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/model.py): `src/mtgda/model.py`

### Model Artifacts

- [Checkpoint loader](https://github.com/pier-tmp/mtgda/blob/main/src/mtgda/checkpoint.py): `src/mtgda/checkpoint.py`
- **Model hub**
- **Pretrained text model**

### Other components

- **Drafting consumer**

## Connections

- Drafting consumer → Assistant API: requests ranking
- Assistant API → Card database: resolves cards
- Assistant API → Inference backends: encodes uncached cards
- Inference backends → Card featurizer: extracts features
- Card featurizer → Mechanic patterns: loads patterns
- Inference backends → Text tokenizer: tokenizes text
- Inference backends → Card encoder: encodes cards
- Card encoder → Pretrained text model: encodes text
- Assistant API → Inference backends: scores draft inputs
- Inference backends → Draft scorer: scores candidates
- Draft network → Card encoder: contains
- Draft network → Draft scorer: contains
- Stateful draft → Assistant API: ranks current pack
- Stateful draft → Card database: validates pick
- Assistant API → Ranked recommendations: returns ranking
- Ranked recommendations → Drafting consumer: presents choices
- Inference backends → Checkpoint loader: loads weights
- Inference backends → Model hub: downloads artifacts
- Model hub → Inference backends: provides model files
- Text tokenizer → Model hub: loads tokenizer
- Checkpoint loader → Pretrained text model: loads pretrained weights