# chaosnyaruko/ondict architecture

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

- Interactive diagram: https://gitdiagram.com/chaosnyaruko/ondict
- Repository: https://github.com/chaosnyaruko/ondict

## Overview

##### Project Overview & Core Purpose
- This is a dictionary application written in Go. It supports online queries (e.g., fetching definitions from the Longman online dictionary), offline queries (by decoding MDX/MDX-like dictionary files), and serves in multiple modes: CLI, interactive “repl”, and HTTP server mode. It also offers a standalone MDX parser tool (“dumpdict”) to convert MDX files into an SQLite database.
- In addition, integrations with external tools (for example, Neovim, FZF, and even hammerspoon for macOS) are provided. Users can also embed dictionary lookup functionality in different workflows.

##### Key Architectural Components
a. User Interface & Integration Layers:
- CLI (main.go, repl.go, server.go command-line options)
- HTTP/Web server (server.go, the assets directory, index.html, and associated static files)
- External integrations (Neovim integration via Lua scripts under the lua/ folder, FZF integration from the fzf/ directory, and hammerspoon usage mentioned in the README)
b. Dictionary Processing Engines:
- Online Engine: Module(s) responsible for fetching and processing online queries (references in sources/ and render/ for processing Longman online definitions).
- Offline/MDX Engine: Components in the decoder/ folder that parse MDX files (mdx.go, related cryptography functions for decoding) and the dumpdict command (cmd/dumpdict) for conversion into a SQLite database.
c. Rendering Layer:
- The render/ directory indicates modular renderers that can output HTML, Markdown, or other formats. These modules transform the processed dictionary entries into user-friendly output for different environments.
d. Data Modeling and Sources:
- The sources/ directory, including several files for managing dictionary entry definitions (e.g., aho_corasick.go for pattern matching, configuration, and parsing functions).
- Schema and Storage: schema.sql defines the database schema along with the “db/” directory (with an example SQLite database file "history.sqlite") that may be used to store query histories and additional data.
e. Utility and Infrastructure:
- Configuration files (e.g., config.json in the user’s config folder as described in the README, and the dotfiles like .dockerignore, .gitignore, and Dockerfile for containerized deployment).
- Build scripts and integration support (Makefile, build.sh, and GitHub workflow definitions under .github/).

##### Relationships and Data Flow
- Start at the User Interface layer (CLI, HTTP request, or an integration call from an editor).
- The query-handling module then selects which dictionary engine to invoke:
- The Online Engine calls out to external web APIs, processes the HTTP response, and passes the data to the renderer.
- The MDX Engine loads a dictionary file, decodes it using modules in the decoder/ folder, and then optionally persists or retrieves entries from the SQLite database.
- The processing engine hands off processed data to the Renderer modules (in render/) which convert entries into HTML, Markdown, or plain text.
- Final results are then returned to the user’s interface (CLI output, HTTP response, or embedded view in an editor).
- There is also an auxiliary “dumpdict” command (inside cmd/dumpdict) that periodically or on-demand converts MDX dictionaries into an SQLite database using schema.sql.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinct modules for UI, processing engines, and rendering.
- Modularity & Extensibility: Extra dictionary sources can be plugged in (the “sources/” folder), and independent decoupled modules allow for multiple integration methods.
- Cross-platform Compatibility: The project’s design supports CLI usage, web server deployment, and integration with different tools, all implemented in Go.
- Use of Standard Configuration Conventions: Adhering to XDG_CONFIG_HOME for storing config and user data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces Layer (blue)
    subgraph "User Interfaces"
        CLI("CLI Entry (main.go)"):::ui
        REPL("REPL Interface (repl.go)"):::ui
        HTTP("HTTP/Web Server (server.go)"):::ui
        ASSETS("Web Assets (assets, index.html, static)"):::ui
        NEOVIM("Neovim Integration (lua scripts)"):::ui
        FZF("FZF Integration (fzf)"):::ui
        HAMMER("Hammerspoon Notes (README.md)"):::ui
    end

    %% Query Handling
    QH("Query Handler"):::core

    %% Processing Engines Layer (green)
    subgraph "Processing Engines"
        subgraph "Online Processing"
            OQ("Online Query Module (sources/ldoceonline.go)"):::proc
            ORE("Online Renderer (render/ldoceonline.go)"):::proc
        end
        subgraph "Offline/MDX Processing"
            MDX("MDX Decoder (decoder/mdx.go)"):::proc
            RIPE("RIPEMD128 Module"):::proc
            SALSA("Salsa20 Module"):::proc
            DUMP("DumpDict Tool (cmd/dumpdict/main.go)"):::proc
        end
    end

    %% Rendering Layer (orange)
    subgraph "Rendering Modules"
        HTML("HTML Renderer (render/html.go)"):::render
        MD("Markdown Renderer (render/markdown.go)"):::render
        MDXRE("MDX Renderer (render/mdx.go)"):::render
    end

    %% Data Modeling & Storage (purple)
    subgraph "Data & Storage"
        DS("Dictionary Sources (sources/aho_corasick.go & sources/mdx.go)"):::data
        DB("SQLite Database (db/history.sqlite)"):::data
        SCH("Database Schema (schema.sql)"):::data
    end

    %% Utility & Infrastructure (gray)
    subgraph "Utilities"
        BUILD("Config & Build Tools (.dockerignore, .gitignore, Dockerfile, Makefile, build.sh)"):::util
        GITHUB("GitHub Workflows (.github/workflows)"):::util
    end

    %% Final Output
    UR("User Response"):::core

    %% Connections from User Interfaces to Query Handler
    CLI --> QH
    REPL --> QH
    HTTP --> QH
    ASSETS --> QH
    NEOVIM --> QH
    FZF --> QH
    HAMMER --> QH

    %% Data Sources feeding Query Handler (configuration/data)
    DS --> QH

    %% Query Handler distributes to Processing Engines
    QH --> OQ
    QH --> MDX

    %% Online Processing Flow
    OQ --> ORE
    ORE --> HTML
    ORE --> MD
    ORE --> MDXRE

    %% Offline Processing Flow
    MDX --> RIPE
    MDX --> SALSA
    MDX --> DUMP
    DUMP --> DB

    %% Offline Processing also provides output to Renderers
    MDX --> HTML
    MDX --> MD
    MDX --> MDXRE

    %% Renderers converge to final output
    HTML --> UR
    MD --> UR
    MDXRE --> UR

    %% Styling Definitions
    classDef ui fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef core fill:#FFFFCC,stroke:#FF9900,stroke-width:2px;
    classDef proc fill:#CCFFCC,stroke:#008000,stroke-width:2px;
    classDef render fill:#FFDAB9,stroke:#FF8C00,stroke-width:2px;
    classDef data fill:#E6CCFF,stroke:#800080,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#696969,stroke-width:2px;

    %% Click Events for User Interfaces
    click CLI "https://github.com/chaosnyaruko/ondict/blob/main/main.go"
    click REPL "https://github.com/chaosnyaruko/ondict/blob/main/repl.go"
    click HTTP "https://github.com/chaosnyaruko/ondict/blob/main/server.go"
    click ASSETS "https://github.com/chaosnyaruko/ondict/tree/main/assets"
    click ASSETS "https://github.com/chaosnyaruko/ondict/blob/main/index.html"
    click ASSETS "https://github.com/chaosnyaruko/ondict/tree/main/static"
    click NEOVIM "https://github.com/chaosnyaruko/ondict/blob/main/lua/ondict.lua"
    click FZF "https://github.com/chaosnyaruko/ondict/blob/main/fzf/filter.go"
    click HAMMER "https://github.com/chaosnyaruko/ondict/blob/main/README.md"

    %% Click Events for Processing Engines
    click OQ "https://github.com/chaosnyaruko/ondict/blob/main/sources/ldoceonline.go"
    click ORE "https://github.com/chaosnyaruko/ondict/blob/main/render/ldoceonline.go"
    click MDX "https://github.com/chaosnyaruko/ondict/blob/main/decoder/mdx.go"
    click RIPE "https://github.com/chaosnyaruko/ondict/blob/main/decoder/ripemd128.go"
    click SALSA "https://github.com/chaosnyaruko/ondict/blob/main/decoder/salsa20.go"
    click DUMP "https://github.com/chaosnyaruko/ondict/blob/main/cmd/dumpdict/main.go"

    %% Click Events for Rendering Modules
    click HTML "https://github.com/chaosnyaruko/ondict/blob/main/render/html.go"
    click MD "https://github.com/chaosnyaruko/ondict/blob/main/render/markdown.go"
    click MDXRE "https://github.com/chaosnyaruko/ondict/blob/main/render/mdx.go"

    %% Click Events for Data & Storage
    click DS "https://github.com/chaosnyaruko/ondict/blob/main/sources/aho_corasick.go"
    click DS "https://github.com/chaosnyaruko/ondict/blob/main/sources/mdx.go"
    click DB "https://github.com/chaosnyaruko/ondict/blob/main/db/history.sqlite"
    click SCH "https://github.com/chaosnyaruko/ondict/blob/main/schema.sql"

    %% Click Events for Utilities
    click BUILD "https://github.com/chaosnyaruko/ondict/tree/main/Makefile"
    click BUILD "https://github.com/chaosnyaruko/ondict/blob/main/.dockerignore"
    click BUILD "https://github.com/chaosnyaruko/ondict/blob/main/.gitignore"
    click BUILD "https://github.com/chaosnyaruko/ondict/tree/main/Dockerfile"
    click BUILD "https://github.com/chaosnyaruko/ondict/blob/main/build.sh"
    click GITHUB "https://github.com/chaosnyaruko/ondict/tree/main/.github/workflows"
```
