# leonhfr/mochi architecture

> Architecture diagram of the GitHub repository leonhfr/mochi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leonhfr/mochi
- Repository: https://github.com/leonhfr/mochi

## Overview

##### Main Components

a. CLI Application Layer
- Entry point through cmd/cli
- Handles user interactions and commands
- Connects to the core synchronization logic

b. GitHub Action Layer
- Separate entry point through cmd/github-action
- Handles automation and CI/CD integration
- Processes inputs and outputs for GitHub Actions

c. Core Service Layer (Internal)
- Action: Handles core operations (dump, load, sync)
- Parser: Processes markdown files
- Converter: Transforms parsed content
- Deck: Manages card collections
- Worker: Handles background tasks and file operations

d. Mochi API Client Layer
- Located in /mochi directory
- Handles API communication with Mochi service
- Manages cards, decks, and templates

e. Supporting Systems
- Configuration management
- File handling
- Request throttling
- Locking mechanism

**[User/GitHub Actions]**
- ↓
**[Entry Points (CLI/GitHub Action)]**
- ↓
**[Core Services Layer]**
- ↓
**[Mochi API Client]**
- ↓
**[External Mochi Service]**

##### Component Relationships

Key interactions:
- File system interactions (markdown files ↔ parser)
- Configuration flow (config → all components)
- API communication flow (client → external service)
- Worker orchestration (worker → various components)

##### Important Details

a. Data Flow
- Markdown files → Parser → Converter → Mochi Cards
- Configuration → System Components
- API Requests → Throttling → External Service

b. Key Subsystems
- Parser subsystem (headings, notes, tables, vocabulary)
- Converter transformations
- Worker pipeline
- Request handling and throttling

##### Architectural Patterns to Highlight

- Pipeline pattern in the conversion process
- Worker pattern for background tasks
- Repository pattern for deck management
- Service layer pattern for core operations

##### The role of supporting systems (throttling, locking, configuration)

- Component types and their visual representations
- Any abbreviations used

This system design should provide a clear understanding of how the tool processes markdown files and synchronizes them with Mochi cards, while highlighting the key architectural decisions and patterns used in the implementation.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Entry Points
    User(("User"))
    GHA(("GitHub Actions"))
    CLI["CLI Application"]:::entrypoint
    GHAC["GitHub Action Runner"]:::entrypoint
    
    %% Core Layer
    subgraph Core["Core Services"]
        Action["Action Service"]:::core
        Parser["Parser System"]:::core
        Converter["Converter System"]:::core
        Deck["Deck Management"]:::core
        Worker["Worker System"]:::core
    end
    
    %% Supporting Systems
    subgraph Support["Supporting Systems"]
        Config["Configuration"]:::support
        FileHandler["File Handler"]:::support
        Throttle["Request Throttler"]:::support
        Lock["Lock Mechanism"]:::support
        ReqHandler["Request Handler"]:::support
        CardMgr["Card Manager"]:::support
    end
    
    %% External Layer
    MochiClient["Mochi API Client"]:::external
    MochiService[("Mochi Service")]:::external
    
    %% Storage
    MDFiles[("Markdown Files")]:::storage
    ConfigFile[("Config File")]:::storage
    LockFile[("Lock File")]:::storage
    
    %% Relationships
    User --> CLI
    GHA --> GHAC
    CLI --> Action
    GHAC --> Action
    
    Action --> Worker
    Worker --> Parser
    Worker --> Converter
    Worker --> Deck
    
    Parser --> MDFiles
    Config --> ConfigFile
    Lock --> LockFile
    
    Deck --> MochiClient
    ReqHandler --> MochiClient
    Throttle --> MochiClient
    MochiClient --> MochiService
    
    %% Support System Connections
    Config --> Action
    FileHandler --> Worker
    Lock --> Worker
    CardMgr --> Deck
    
    %% Click Events
    click CLI "https://github.com/leonhfr/mochi/tree/master/cmd/cli"
    click GHAC "https://github.com/leonhfr/mochi/tree/master/cmd/github-action"
    click Action "https://github.com/leonhfr/mochi/tree/master/internal/action"
    click Parser "https://github.com/leonhfr/mochi/tree/master/internal/parser"
    click Converter "https://github.com/leonhfr/mochi/tree/master/internal/converter"
    click Deck "https://github.com/leonhfr/mochi/tree/master/internal/deck"
    click Worker "https://github.com/leonhfr/mochi/tree/master/internal/worker"
    click MochiClient "https://github.com/leonhfr/mochi/tree/master/mochi"
    click Config "https://github.com/leonhfr/mochi/tree/master/internal/config"
    click FileHandler "https://github.com/leonhfr/mochi/tree/master/internal/file"
    click Throttle "https://github.com/leonhfr/mochi/tree/master/internal/throttle"
    click Lock "https://github.com/leonhfr/mochi/tree/master/internal/lock"
    click ReqHandler "https://github.com/leonhfr/mochi/tree/master/internal/request"
    click CardMgr "https://github.com/leonhfr/mochi/tree/master/internal/card"
    click ConfigFile "https://github.com/leonhfr/mochi/blob/master/testdata/mochi.yml"
    click LockFile "https://github.com/leonhfr/mochi/blob/master/testdata/mochi-lock.json"
    
    %% Styles
    classDef entrypoint fill:#2374ab
    classDef core fill:#57a773
    classDef support fill:#ffc857
    classDef external fill:#a8a8a8
    classDef storage fill:#d1d1d1
    
    %% Legend
    subgraph Legend
        L1[Entry Points]:::entrypoint
        L2[Core Services]:::core
        L3[Supporting Systems]:::support
        L4[External Services]:::external
        L5[(Storage)]:::storage
    end
```
