# itsn80/bbg-tcg-sorter architecture

> Architecture diagram of the GitHub repository itsn80/bbg-tcg-sorter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itsn80/bbg-tcg-sorter
- Repository: https://github.com/itsn80/bbg-tcg-sorter

## Overview

BBG TCG Sorter is a Raspberry Pi card-sorting appliance operated through a password-gated Flask UI. Its principal workflow feeds a card, captures and recognizes it, looks up card metadata, applies bin rules, and routes it with servos. The README documents AWS Rekognition/Ollama-compatible recognition, Scryfall lookup, ten bins, and live status/settings; sampled excerpts additionally show feed orchestration and LED control. Some workflow links rely on README documentation because the relevant orchestration code was not excerpted.

Main entry points: [`Basic-Website.py`](https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py) (Flask App), [`scripts/Read-Card.py`](https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Read-Card.py) (Capture And Identify), [`scripts/Feed-Card.py`](https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Feed-Card.py) (Feed Cycle), [`templates`](https://github.com/itsn80/bbg-tcg-sorter/tree/main/templates) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Control"]
  node_flask["Flask App<br/>[Basic-Website.py]"]
  node_webui["Web UI"]
  node_auth["Login And Settings<br/>[Basic-Website.py]"]
  node_sortloop["Sort Orchestrator<br/>[Basic-Website.py]"]
  node_status["Live Status<br/>[Basic-Website.py]"]
end

subgraph group_recognition["Card Recognition"]
  node_recognizer["Capture And Identify<br/>[Read-Card.py]"]
end

subgraph group_routing["Feed And Routing"]
  node_feed["Feed Cycle<br/>[Feed-Card.py]"]
  node_binrules["Bin Rule Matching<br/>[Basic-Website.py]"]
end

subgraph group_hardware["Hardware Control"]
  node_servos["Servo Controller"]
  node_motorsensors["Motors And Sensors<br/>[Feed-Card.py]"]
  node_led["LED Controller<br/>[led_controller.py]"]
end

subgraph group_state["Configuration And State"]
  node_config["App Configuration"]
  node_bininfo["Bin Rules Data"]
end

node_operator(("Operator"))
node_camera["Pi Camera"]
node_aws["AWS Rekognition"]
node_ollama["Ollama-Compatible Vision"]
node_scryfall["Scryfall Lookup"]
node_smtp["SMTP Service"]

node_operator -->|"uses"| node_webui
node_webui -.->|"submits requests"| node_flask
node_flask -->|"authenticates"| node_auth
node_flask -->|"starts sorting"| node_sortloop
node_sortloop -->|"runs feed script"| node_feed
node_sortloop -->|"requests identification"| node_recognizer
node_recognizer -->|"captures images"| node_camera
node_recognizer -->|"recognizes text"| node_aws
node_recognizer -->|"recognizes image"| node_ollama
node_recognizer -->|"looks up card"| node_scryfall
node_sortloop -->|"matches card"| node_binrules
node_sortloop -->|"routes card"| node_servos
node_feed -->|"drives and senses"| node_motorsensors
node_feed -.->|"invokes servo script"| node_servos
node_flask -->|"controls LEDs"| node_led
node_flask -->|"reads and writes"| node_config
node_flask -->|"reads and writes"| node_bininfo
node_binrules -->|"loads rules"| node_bininfo
node_flask -->|"serves status"| node_status
node_flask -.->|"sends summaries"| node_smtp

click node_flask "https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py"
click node_webui "https://github.com/itsn80/bbg-tcg-sorter/tree/main/templates"
click node_auth "https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py"
click node_sortloop "https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py"
click node_feed "https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Feed-Card.py"
click node_recognizer "https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Read-Card.py"
click node_binrules "https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py"
click node_servos "https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/servo_controller.py"
click node_motorsensors "https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Feed-Card.py"
click node_led "https://github.com/itsn80/bbg-tcg-sorter/blob/main/led_controller.py"
click node_config "https://github.com/itsn80/bbg-tcg-sorter/blob/main/storage/config-default.json"
click node_bininfo "https://github.com/itsn80/bbg-tcg-sorter/blob/main/storage/bin-info-default.json"
click node_status "https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.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_flask,node_webui,node_auth,node_sortloop,node_status toneBlue
class node_recognizer toneAmber
class node_feed,node_binrules toneMint
class node_servos,node_motorsensors,node_led toneRose
class node_config,node_bininfo,node_operator,node_camera,node_aws,node_ollama,node_scryfall,node_smtp toneIndigo
```

## Components

### Web Control

- [Flask App](https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py): `Basic-Website.py`
- [Web UI](https://github.com/itsn80/bbg-tcg-sorter/tree/main/templates): `templates`
- [Login And Settings](https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py): `Basic-Website.py`
- [Sort Orchestrator](https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py): `Basic-Website.py`
- [Live Status](https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py): `Basic-Website.py`

### Card Recognition

- [Capture And Identify](https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Read-Card.py): `scripts/Read-Card.py`

### Feed And Routing

- [Feed Cycle](https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Feed-Card.py): `scripts/Feed-Card.py`
- [Bin Rule Matching](https://github.com/itsn80/bbg-tcg-sorter/blob/main/Basic-Website.py): `Basic-Website.py`

### Hardware Control

- [Servo Controller](https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/servo_controller.py): `scripts/servo_controller.py`
- [Motors And Sensors](https://github.com/itsn80/bbg-tcg-sorter/blob/main/scripts/Feed-Card.py): `scripts/Feed-Card.py`
- [LED Controller](https://github.com/itsn80/bbg-tcg-sorter/blob/main/led_controller.py): `led_controller.py`

### Configuration And State

- [App Configuration](https://github.com/itsn80/bbg-tcg-sorter/blob/main/storage/config-default.json): `storage/config-default.json`
- [Bin Rules Data](https://github.com/itsn80/bbg-tcg-sorter/blob/main/storage/bin-info-default.json): `storage/bin-info-default.json`

### Other components

- **Operator**
- **Pi Camera**
- **AWS Rekognition**
- **Ollama-Compatible Vision**
- **Scryfall Lookup**
- **SMTP Service**

## Connections

- Operator → Web UI: uses (evidence: `README.md`)
- Web UI → Flask App: submits requests
- Flask App → Login And Settings: authenticates (evidence: `Basic-Website.py`)
- Flask App → Sort Orchestrator: starts sorting (evidence: `Basic-Website.py`)
- Sort Orchestrator → Feed Cycle: runs feed script (evidence: `Basic-Website.py`)
- Sort Orchestrator → Capture And Identify: requests identification (evidence: `README.md`)
- Capture And Identify → Pi Camera: captures images (evidence: `scripts/Read-Card.py`)
- Capture And Identify → AWS Rekognition: recognizes text (evidence: `scripts/Read-Card.py`)
- Capture And Identify → Ollama-Compatible Vision: recognizes image (evidence: `scripts/Read-Card.py`)
- Capture And Identify → Scryfall Lookup: looks up card (evidence: `scripts/Read-Card.py`)
- Sort Orchestrator → Bin Rule Matching: matches card (evidence: `README.md`)
- Sort Orchestrator → Servo Controller: routes card (evidence: `README.md`)
- Feed Cycle → Motors And Sensors: drives and senses (evidence: `scripts/Feed-Card.py`)
- Feed Cycle → Servo Controller: invokes servo script
- Flask App → LED Controller: controls LEDs (evidence: `Basic-Website.py`)
- Flask App → App Configuration: reads and writes (evidence: `README.md`)
- Flask App → Bin Rules Data: reads and writes (evidence: `README.md`)
- Bin Rule Matching → Bin Rules Data: loads rules (evidence: `README.md`)
- Flask App → Live Status: serves status (evidence: `Basic-Website.py`)
- Flask App → SMTP Service: sends summaries (evidence: `README.md`)
