# bboatman/magicdeckgenerator architecture

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

- Interactive diagram: https://gitdiagram.com/bboatman/magicdeckgenerator
- Repository: https://github.com/bboatman/magicdeckgenerator

## Overview

##### Main Components
- Backend Application (Python): This is encapsulated in the magicDeckGenerator directory. Key modules include:
– Core Engine (magicDeckGenerator/main.py) launching workflows.
– Libraries under magicDeckGenerator/lib handling:
▪ Deck and DeckMember classes.
▪ Model definitions (e.g., Card).
▪ Data scraping and scraping abstractions (e.g., AbstractDataScraper, MtgTop8Scraper, scraper.py, deckScraper.py).
▪ Card vectorization components (cardVectorizor, vectorize module's main.py) which also includes the cosine_sim module.
▪ Utility modules (log.py, service.py, timer.py).
- Frontend Visualizer (Angular): Found under magicVisualizer, the Angular project is responsible for visualizing vectorized card relationships and deck structures.
– It includes assets (CSV files of graph points), Angular routing, and Angular Material-based views.
- Database (PostgreSQL via Docker): Managed by docker-compose.yml and init scripts (in postgres/migrations), the DB stores card and deck data, and is updated through migrations on container startup.

##### Diagraming Relationships and Interactions
– Data Scraping: Components within lib/dataScrapers and deckScraper.py.
– Card Vectorization: Modules in cardVectorizor and lib/vectorize (including cosine_sim).
– Core Logic: Deck/DeckMember modules, Models (Card), logging, and service utilities.

##### Architectural Patterns and Design Principles
- Modularity in the Python backend: modules are separated by responsibility (data scraping vs. vectorization vs. core deck modeling).
- Mention the loosely coupled integration between the generation engine and visualization tool – one processes data while the other visualizes it.
- Layered approach: data is scraped, then vectorized (using cosine similarity and other mathematical measures), and finally utilized for deck generation and visualization.
- Use of containerization (Docker) to standardize the database environment.

##### Specific Technologies and Frameworks
- Python for the backend.
- PostgreSQL as the database (managed via docker-compose).
- Angular/Angular Material for the frontend application.
- Docker for containerization.
- Additionally, list any notable libraries such as those used in vectorization (cosine_sim) or data scraping.

##### Important Elements
– “Python Backend Service (magicDeckGenerator)” subdivided as needed (Scraper, Vectorizer, Logic).
– “Angular Visualizer (magicVisualizer)”.
– “PostgreSQL Database” (inside a Docker container).
– Denote the workflow from scraping → vectorization → deck generation → visualizer.
– Indicate read/write flows between the backend and the database.
- Annotations for significant external tools (Docker, Node package management for Angular).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Python Backend Service (magicDeckGenerator)
    subgraph "Python Backend Service (magicDeckGenerator)"
        A["Core Engine (main.py)"]:::backendBox

        subgraph "Data Scraping"
            B["AbstractDataScraper"]:::backendBox
            C["MtgTop8Scraper"]:::backendBox
            D["scraper.py"]:::backendBox
            E["deckScraper.py"]:::backendBox
        end

        subgraph "Card Vectorization"
            F["cardVectorizor.py"]:::backendBox
            G["cosine_sim.py"]:::backendBox
            H["vectorize/main.py"]:::backendBox
        end

        subgraph "Deck Management & Models"
            I["Deck & DeckMember (Deck.py, DeckMember.py)"]:::backendBox
            J["Model Definition (Card.py)"]:::backendBox
        end

        subgraph "Utility Modules"
            K["log.py"]:::backendBox
            L["service.py"]:::backendBox
            M["timer.py"]:::backendBox
        end
    end

    %% PostgreSQL Database (Docker)
    DB["PostgreSQL Database (Docker)"]:::dbBox

    %% Angular Visualizer (magicVisualizer)
    FV["Angular Visualizer (magicVisualizer)"]:::frontendBox

    %% Environment/Setup Group
    subgraph "Environment/Setup"
        EN1["Python Dependencies (requirements.txt)"]:::envBox
        EN2["Docker Compose (for DB)"]:::envBox
        EN3["Angular Dependencies (package.json)"]:::envBox
    end

    %% Connections within Backend Workflow
    A -->|"triggers"| B
    B -->|"initiates scraping"| F
    F -->|"vectorizes data"| I

    %% Interactions with Database and Frontend
    I -->|"stores data"| DB
    I -->|"sends processed data"| FV

    %% Environment influences
    EN1 --> A
    EN2 --> DB
    EN3 --> FV

    %% Click Events for Python Backend Service
    click A "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/main.py"
    click B "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/dataScrapers/AbstractDataScraper.py"
    click C "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/dataScrapers/MtgTop8Scraper.py"
    click D "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/scraper.py"
    click E "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/deckScraper.py"
    click F "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/cardVectorizor.py"
    click G "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/cosine_sim.py"
    click H "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/vectorize/main.py"
    click I "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/Deck.py"
    click J "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/Models/Card.py"
    click K "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/log.py"
    click L "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/service.py"
    click M "https://github.com/bboatman/magicdeckgenerator/blob/master/magicDeckGenerator/lib/timer.py"

    %% Click Events for PostgreSQL Database
    click DB "https://github.com/bboatman/magicdeckgenerator/blob/master/docker-compose.yml"
    click DB "https://github.com/bboatman/magicdeckgenerator/blob/master/postgres/migrations/00001_init.up.sql"

    %% Click Event for Angular Visualizer
    click FV "https://github.com/bboatman/magicdeckgenerator/tree/master/magicVisualizer"

    %% Click Events for Environment/Setup
    click EN1 "https://github.com/bboatman/magicdeckgenerator/blob/master/requirements.txt"
    click EN2 "https://github.com/bboatman/magicdeckgenerator/blob/master/docker-compose.yml"
    click EN3 "https://github.com/bboatman/magicdeckgenerator/blob/master/magicVisualizer/package.json"

    %% Styles
    classDef backendBox fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef frontendBox fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef dbBox fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef envBox fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
