# alexiiko/transcardify architecture

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

- Interactive diagram: https://gitdiagram.com/alexiiko/transcardify
- Repository: https://github.com/alexiiko/transcardify

## Overview

##### Main Components
- Input Module: Although there isn’t a dedicated “input” folder, the usage instructions in the README note that the application expects a JSON file with highlights. Represent this as an external input source that feeds data into the system.
- Main Application Controller (main.py): This file acts as the coordinator, handling user input, guiding the workflow, and orchestrating the other components.
- Translation Module (translator.py): This component interacts with the googletrans library to translate vocabulary. Indicate a dependency on the external Google Translation API/service.
- Card Generation Module (card_generator.py): Responsible for generating the Anki card package using the genanki library. This module may also handle calls to the free dictionary API for word definitions.
- Language Codes Helper (language_codes.py): Serves as a lookup for language codes, which is likely referenced by the translator module.
- Executable Packaging: Represent the “pyinstaller” produced executables (linux-executable & windows-executable.exe) as deployment artifacts that wrap the application into standalone binaries.

##### Relationships and Data Flow
- The Translator module should be linked to the external service (Google Translation) and reference the Language Codes Helper, suggesting that it uses this utility for proper language support.
- Similarly, the Card Generator module should be illustrated as connecting to both genanki (for Anki deck creation) and the Free Dictionary API, representing the fetching of word definitions.

##### Architectural Patterns and Design Principles
- Modular Design: Each Python script (main.py, translator.py, card_generator.py, language_codes.py) encapsulates a specific functionality, which is a clean modular approach.
- Separation of Concerns: The system clearly partitions responsibilities (input handling, translation, card generation) to maintain maintainability.
- Dependency on External Services: Show that the translator and card generator are not standalone; they integrate with external libraries and APIs.
- Build and Deployment: Emphasize that the executable files generated via PyInstaller wrap the entire application for easy distribution on different operating systems.

##### Relevant Technologies and Frameworks
- Python as the core programming language.
- googletrans for translation services.
- genanki for generating Anki decks.
- Free Dictionary API for fetching definitions.
- PyInstaller for creating platform-specific executables.
- Additionally, handling JSON input (the file format expected from bookcision) is key to the data flow.

##### Final Advice
- Remember to detail not only the modules and their interactions, but also the build/deployment aspect (illustrating that the Python scripts are bundled into executables with PyInstaller).
- Try to capture as many points from the README as possible, such as prerequisites and external services, to give a comprehensive overview of how the system functions from input to final bytecode.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    Input["JSON Highlights (Input)"]:::external

    %% Internal Modules
    MC["Main Controller (main.py)"]:::internal
    T["Translator (translator.py)"]:::internal
    LC["Language Codes Helper (language_codes.py)"]:::internal
    CG["Card Generator (card_generator.py)"]:::internal

    %% External Services and Libraries
    GTrans["Google Translation API"]:::external
    Genanki["genanki Library"]:::external
    DictAPI["Free Dictionary API"]:::external

    %% Final Output
    APKG["Generated .apkg (Anki Deck)"]:::internal

    %% Deployment Artifacts
    subgraph "Deployment Artifacts"
        LinuxExecutable["Linux Executable"]:::deployment
        WindowsExecutable["Windows Executable"]:::deployment
    end

    %% Data Flow
    Input -->|"feeds"| MC
    MC -->|"calls"| T
    MC -->|"calls"| CG

    T -->|"uses"| GTrans
    T -->|"looks-up"| LC

    CG -->|"calls"| Genanki
    CG -->|"calls"| DictAPI
    CG -->|"produces"| APKG

    %% Deployment Packaging (bundling the main app into executables)
    MC -->|"packaged_by"| LinuxExecutable
    MC -->|"packaged_by"| WindowsExecutable

    %% Styles
    classDef internal fill:#9fdfbf,stroke:#0a8000,stroke-width:2px;
    classDef external fill:#f9cb9c,stroke:#b85400,stroke-width:2px;
    classDef deployment fill:#cfe2f3,stroke:#1155cc,stroke-width:2px;

    %% Click Events
    click MC "https://github.com/alexiiko/transcardify/blob/master/main.py"
    click T "https://github.com/alexiiko/transcardify/blob/master/translator.py"
    click LC "https://github.com/alexiiko/transcardify/blob/master/language_codes.py"
    click CG "https://github.com/alexiiko/transcardify/blob/master/card_generator.py"
    click LinuxExecutable "https://github.com/alexiiko/transcardify/tree/master/linux-executable"
    click WindowsExecutable "https://github.com/alexiiko/transcardify/blob/master/windows-executable.exe"
```
