# dai-motoki/zoltraak architecture

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

- Interactive diagram: https://gitdiagram.com/dai-motoki/zoltraak
- Repository: https://github.com/dai-motoki/zoltraak

## Overview

##### Main Components in the System

- Command Line Interface (CLI) Layer:
- Represented by files like zoltraak/cli.py.
- Provides the entry point for users to input natural language prompts and options (e.g., choice of compiler).

- Conversion/Compilation Core:
- The converter module (zoltraak/converter.py) and code generator modules (zoltraak/gencode.py and gencodebase.py) form the heart of prompt compilation.
- They take input natural language instructions (呪文) and process them through various “compiler” approaches as outlined (e.g., dev_func, dev_obj, biz_consult) to generate requirements and code.

- Grimoires (Modular “Magic” Spell Sets):
- The zoltraak/grimoires directory is organized into several submodules:
▪ Compiler: Contains a variety of domain-specific markdown files and scripts for converting prompts into detailed output.
▪ Formatter: Holds files (e.g., md_comment.md and language-specific variations) that define how prompts or generated code should be formatted.
▪ Encryption, Interpretspec, SoftDB, and Developer: Provide additional capabilities, like encryption of the “呪文” and support for developer-specific compilations.

- LLM Integration:
- The zoltraak/llms directory (with files such as claude.py and gemini.py) interfaces with external language model APIs.

- Utility Components:
- Folder zoltraak/utils contains helper utilities (e.g., process_text.py, prompt_import.py) that aid processing.
- Tests, scripts (run_tests.sh), and CI/CD integration files should be represented as supporting/testing infrastructure, ensuring that the core conversion logic is maintained.

- Package & Distribution:
- Files like setup.py, requirements.txt, and shell scripts for updating/upload (update_and_upload.sh, update_version.py) indicate the packaging, deployment, and distribution pipeline.

##### Relationships and Data Flow

- User Input:

- Conversion Flow:
- From the CLI, show data flow into the converter (zoltraak/converter.py), which in turn routes the prompt to one or more compilers defined in the Grimoires.

- Integration with LLMs:
- That during conversion the system may call out to external LLMs via the llms layer (e.g., via claude.py).

- Output Generation:
- After conversion and formatting (using the Formatter modules in grimoires/formatter), output files (requirements documents, generated Python code, Markdown files) are produced.

- Caching & CI/CD:
- A caching component that checks file hashes (as described under “キャッシング” in the README) to avoid unnecessary reconversions.

##### Architectural Patterns and Design Principles

- Modularity:
- Plugin-like nature of the Grimoires, where different “compiler” and “formatter” modules can be added or updated independently.

- Separation of Concerns:

- Extensibility:
- Extensibility points where additional compilers or output formatters can be integrated. The directory structure under grimoires is a key example.

##### Technologies and Frameworks

- Python is the primary language, with modules such as setuptools for packaging.
- Shell scripting is used for test execution and deployment.
- External APIs: Anthropic’s API (and possibly others like Gemini) are key for LLM functionality.
- GitHub Actions (.github/workflows) signals CI/CD integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U("User/Developer"):::user

    %% CLI Layer
    subgraph "CLI Layer"
        CLI("CLI Interface"):::cli
    end

    %% Conversion Engine
    subgraph "Core Conversion Engine"
        CONV("Converter (zoltraak/converter.py)"):::core
        CODE("Code Generator (zoltraak/gencode.py)"):::core
        BASE("Gencode Base (zoltraak/gencodebase.py)"):::core
    end

    %% Grimoires Modules
    subgraph "Grimoires Modules"
        COMP("Compiler Modules"):::grim
        FORM("Formatter Modules"):::grim
        DEVEL("Developer Modules"):::grim
        ENCRYPT("Encryption Modules"):::grim
        INTERP("Interpretspec Modules"):::grim
        ARCH("Architect"):::grim
    end

    %% LLM Integration
    subgraph "LLM Integration"
        LLM("LLM Interface (zoltraak/llms)"):::llm
        EXLLM("External LLM Services (Anthropic_API)"):::external
    end

    %% Output & Caching
    subgraph "Output & Caching"
        OUTPUT("Generated Output"):::output
        CACHE("Caching Component"):::cache
    end

    %% Utilities & Testing
    subgraph "Utilities & Testing"
        UTILS("Utility Components (zoltraak/utils)"):::utility
        subgraph "Automated Testing & CI/CD"
            TESTS("Tests (tests)"):::utility
            WORKFLOWS("Workflows (.github/workflows)"):::utility
            RUN_TESTS("run_tests.sh"):::utility
            UPDATE_UPLOAD("update_and_upload.sh"):::utility
            UPDATE_VERSION("update_version.py"):::utility
        end
    end

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        PKG("Packaging (setup.py)"):::pkg
        REQ("Dependencies (requirements.txt)"):::pkg
    end

    %% Connections
    U -->|"Prompt_Input"| CLI
    CLI -->|"Submit_Prompt"| CONV
    CONV -->|"Invoke"| CODE
    CONV -->|"Invoke"| BASE
    CODE -->|"Generate_Code"| OUTPUT
    BASE -->|"Generate_Code"| OUTPUT
    CONV -->|"Select_Compiler"| COMP
    CONV -->|"Invoke_Formatter"| FORM
    CONV -->|"Dev_Compilation"| DEVEL
    CONV -->|"Encryption_Check"| ENCRYPT
    CONV -->|"Interpret_Spell"| INTERP
    CONV -->|"Cache_Check"| CACHE
    CONV <-->|"LLM_Calls"| LLM
    LLM <-->|"Anthropic_API"| EXLLM
    UTILS -->|"Support_Functions"| CONV
    TESTS -->|"Automated_Testing"| CONV
    WORKFLOWS -->|"CI_CD_Flow"| PKG
    RUN_TESTS -->|"Executes_Tests"| TESTS
    UPDATE_UPLOAD -->|"Deployment_Script"| TESTS
    UPDATE_VERSION -->|"Version_Update"| TESTS
    TESTS -->|"Feedback"| CACHE

    %% Click Events
    click CLI "https://github.com/dai-motoki/zoltraak/blob/main/zoltraak/cli.py"
    click CONV "https://github.com/dai-motoki/zoltraak/blob/main/zoltraak/converter.py"
    click CODE "https://github.com/dai-motoki/zoltraak/blob/main/zoltraak/gencode.py"
    click BASE "https://github.com/dai-motoki/zoltraak/blob/main/zoltraak/gencodebase.py"
    click COMP "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/grimoires/compiler"
    click FORM "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/grimoires/formatter"
    click DEVEL "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/grimoires/developer"
    click ENCRYPT "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/grimoires/encryption"
    click INTERP "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/grimoires/interpretspec"
    click ARCH "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/grimoires/architect"
    click LLM "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/llms"
    click UTILS "https://github.com/dai-motoki/zoltraak/tree/main/zoltraak/utils"
    click TESTS "https://github.com/dai-motoki/zoltraak/tree/main/tests"
    click WORKFLOWS "https://github.com/dai-motoki/zoltraak/tree/main/.github/workflows"
    click RUN_TESTS "https://github.com/dai-motoki/zoltraak/blob/main/scripts/run_tests.sh"
    click UPDATE_UPLOAD "https://github.com/dai-motoki/zoltraak/blob/main/update_and_upload.sh"
    click UPDATE_VERSION "https://github.com/dai-motoki/zoltraak/blob/main/update_version.py"
    click PKG "https://github.com/dai-motoki/zoltraak/blob/main/setup.py"
    click REQ "https://github.com/dai-motoki/zoltraak/blob/main/requirements.txt"

    %% Styles
    classDef user fill:#f4d03f,stroke:#000,stroke-width:1px;
    classDef cli fill:#85c1e9,stroke:#000,stroke-width:1px;
    classDef core fill:#aed6f1,stroke:#000,stroke-width:1px;
    classDef grim fill:#f9e79f,stroke:#000,stroke-width:1px;
    classDef llm fill:#fadbd8,stroke:#000,stroke-width:1px;
    classDef external fill:#f5b7b1,stroke:#000,stroke-width:1px;
    classDef output fill:#d5f5e3,stroke:#000,stroke-width:1px;
    classDef cache fill:#e8daef,stroke:#000,stroke-width:1px;
    classDef utility fill:#d6eaf8,stroke:#000,stroke-width:1px;
    classDef pkg fill:#fef9e7,stroke:#000,stroke-width:1px;
```
