# npcnixel/genanki-go architecture

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

- Interactive diagram: https://gitdiagram.com/npcnixel/genanki-go
- Repository: https://github.com/npcnixel/genanki-go

## Overview

##### Main components
- API / Fluent-Builder Layer
– Models: `models.go` defines Model and Field structures and methods to customize CSS and fields.
– Decks & Notes: `models.go` and `package.go` include Deck and Note builders with method chaining (`AddNote`, `SetCSS`, etc.).
- Media Manager
– `media.go`: responsible for collecting media (images, audio, video) into memory until packaging.
- Database Writer
– `database.go`: encapsulates creation of an in-memory or on-disk SQLite DB, schema creation (tables for notes, cards, models, decks), and insertion of all records.
- Package Assembler
– `package.go`: orchestrates the above components: takes decks, models, media; calls the database writer; and uses Go’s zip utilities to bundle the SQLite DB and media into an `.apkg` file.
- File System / I/O
– Under the Package Assembler: writes the final zip to disk via `WriteToFile`.
- Examples / Tests (external)
– `examples/`: show how consumers use the API.
– `tests/`: validate correctness of chaining, deck/model/note creation, and end-to-end integration.

##### Relationships & Data Flow
1) User code (examples) calls API Layer → constructs Models, Decks, Notes
2) API Layer accumulates data in memory (builder objects)
3) User invokes `NewPackage(...).AddModel(...).AddMedia(...).WriteToFile(...)`
4) Package Assembler calls Database Writer → creates SQLite file (in memory or temp file)
5) Database Writer populates tables for decks, models, notes, cards
6) Package Assembler zips the DB file + media assets into an `.apkg` ZIP archive
7) File I/O flushes the ZIP to disk

##### Architectural Patterns & Design Principles
- Fluent/Method-Chaining Builder Pattern (Deck.AddNote(...).AddNote(...)…)
- Separation of Concerns: builders (API) vs persistence (database.go) vs packaging (package.go) vs media (media.go)
- Single Responsibility: each Go file/module owns one area
- Optional Debug Logging: toggled via environment variable or `pkg.SetDebug(true)`, woven through the Database Writer

##### Technologies & Frameworks
- Go standard library – SQLite driver (via `database/sql`), `archive/zip`, `os` I/O
- No external services – everything runs in‐process
- Tests use Go’s `testing` package

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Consumers
    subgraph "External Consumers"
        direction TB
        ExampleBasic["Basic Example"]:::external
        ExampleAdvanced["Advanced Example"]:::external
        TestsChaining["chaining_test.go"]:::external
        TestsDecks["decks_test.go"]:::external
        TestsIntegration["integration_test.go"]:::external
        TestsModels["models_test.go"]:::external
        TestsNotes["notes_test.go"]:::external
    end

    %% Core Layers
    subgraph "API / Fluent-Builder Layer"
        direction TB
        API_Layer_Models["Models (models.go)"]:::builder
        API_Layer_Builders["Deck & Note Builders (package.go)"]:::builder
    end

    Media_Manager["Media Manager (media.go)"]:::builder
    Database_Writer["Database Writer (database.go)"]:::persistence
    Package_Assembler["Package Assembler (package.go)"]:::packaging
    File_IO["File System I/O"]:::packaging

    %% Flows
    ExampleBasic -->|"uses API"| API_Layer_Models
    ExampleAdvanced -->|"uses API"| API_Layer_Builders
    TestsChaining -->|"tests chaining"| API_Layer_Builders
    TestsDecks -->|"tests deck/note"| API_Layer_Builders
    TestsIntegration -->|"end-to-end"| Package_Assembler
    TestsModels -->|"tests models"| API_Layer_Models
    TestsNotes -->|"tests notes"| API_Layer_Builders

    API_Layer_Models -->|"Model structs"| Package_Assembler
    API_Layer_Builders -->|"Deck + Notes"| Package_Assembler
    Package_Assembler -->|"invokes"| Database_Writer
    Package_Assembler -->|"collects"| Media_Manager
    Database_Writer -->|"creates SQLite file"| Package_Assembler
    Package_Assembler -->|"assembles .apkg zip"| File_IO

    %% Click Events
    click API_Layer_Models "https://github.com/npcnixel/genanki-go/blob/main/models.go"
    click API_Layer_Builders "https://github.com/npcnixel/genanki-go/blob/main/package.go"
    click Media_Manager "https://github.com/npcnixel/genanki-go/blob/main/media.go"
    click Database_Writer "https://github.com/npcnixel/genanki-go/blob/main/database.go"
    click Package_Assembler "https://github.com/npcnixel/genanki-go/blob/main/package.go"
    click ExampleBasic "https://github.com/npcnixel/genanki-go/blob/main/examples/basic_example/main.go"
    click ExampleAdvanced "https://github.com/npcnixel/genanki-go/blob/main/examples/advanced_example/main.go"
    click TestsChaining "https://github.com/npcnixel/genanki-go/blob/main/tests/chaining_test.go"
    click TestsDecks "https://github.com/npcnixel/genanki-go/blob/main/tests/decks_test.go"
    click TestsIntegration "https://github.com/npcnixel/genanki-go/blob/main/tests/integration_test.go"
    click TestsModels "https://github.com/npcnixel/genanki-go/blob/main/tests/models_test.go"
    click TestsNotes "https://github.com/npcnixel/genanki-go/blob/main/tests/notes_test.go"

    %% Styles
    classDef builder fill:#add8e6,stroke:#333,stroke-width:1px
    classDef persistence fill:#90ee90,stroke:#333,stroke-width:1px
    classDef packaging fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
