# tsuno08/aimai architecture

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

- Interactive diagram: https://gitdiagram.com/tsuno08/aimai
- Repository: https://github.com/tsuno08/aimai

## Overview

##### Project Type and Purpose
- This is a command‑line interface (CLI) tool (“Aimai CLI”) that converts Japanese natural‑language instructions into shell commands.
- It follows an MVC‑style decomposition (src/model.py, src/view.py, src/controller.py) with a thin CLI entrypoint (src/cli.py) and a launcher script (bin/aimai).

##### Key Components
a. CLI Entrypoint (bin/aimai → src/cli.py)
- `bin/aimai`: Unix‑executable that bootstraps the Python environment and calls `src/cli.py`.
- `src/cli.py`: Uses Click to parse user arguments and dispatch to the controller.
b. Controller Layer (src/controller.py)
- Receives parsed input from `cli.py`.
- Coordinates the flow: calls the model to generate command candidates and passes results to the view.
c. Model Layer (src/model.py)
- Contains business logic and data structures.
- Wraps the Google Generative AI (Gemini) API client to translate natural language into shell commands.
- Handles environment variable loading (python‑dotenv) and API key management.
- May invoke subprocess or shell to execute confirmed commands.
d. View Layer (src/view.py)
- Renders output in the terminal using Rich for formatting.
e. External Services
- Google Generative AI (Gemini 1.5 Flash) via `google-generativeai` SDK.

##### Data and Control Flow
1. User runs `aimai "指示文"` in shell. → `bin/aimai` → `src/cli.py`.
2. `cli.py` (Click) parses the argument and calls `controller.handle_request(natural_text)`.
3. `Controller` invokes `Model.generate_commands(natural_text)`.
4. `Model` sends request to Gemini API, receives a set of shell command candidates.
5. `Controller` passes candidates to `View.present_choices(candidates)`.
6. `View` displays formatted list (Rich) and lets the user select one (PromptToolkit).
7. On user confirmation, `Controller` tells `Model` to execute the chosen command.
8. `Model` runs the command in the shell and returns the result.
9. `View` prints execution output.

##### Architectural Patterns and Principles
- MVC Separation:
- Model: API integration & execution logic.
- View: Presentation & interactive UI.
- Controller: Orchestration between model/view.
- Single Responsibility: each module focuses on one concern.
- Dependency Injection via function parameters (e.g., injecting API client into model).
- External‑service boundary clearly marked (Gemini API).

- Each component clearly labeled with file name and responsibility.
- Internal modules (blue),
- External services (green),
- Scripts & shell (gray).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Shell(("Shell\nUser's terminal")):::script
    Launcher["Launcher Script\nbin/aimai"]:::script
    CLI["CLI Parser\nsrc/cli.py\n(Click)"]:::internal
    Controller["Controller\nsrc/controller.py"]:::internal
    Model["Model\nsrc/model.py\n(google-generativeai, dotenv)"]:::internal
    View["View\nsrc/view.py\n(Rich, PromptToolkit)"]:::internal
    API["Gemini API\n(Google Generative AI)"]:::external
    Subproc(("Subprocess Executor\n(shell execution)")):::script

    Shell -->|"1. runs"| Launcher
    Launcher -->|"2. bootstraps & calls"| CLI
    CLI -->|"3. handle_request()"| Controller
    Controller -->|"4. generate_commands()"| Model
    Model -->|"5. API request"| API
    API -->|"6. responses"| Model
    Controller -->|"7. present_choices()"| View
    View -->|"8. selection"| Controller
    Controller -->|"9. execute_command()"| Model
    Model -->|"10. executes"| Subproc
    Subproc -->|"11. output"| Model
    Model -->|"12. returns result"| Controller
    Controller -->|"13. display_output()"| View
    View -->|"14. prints"| Shell

    subgraph Legend
        L1["Script & Shell"]:::script
        L2["Internal Module"]:::internal
        L3["External Service"]:::external
    end

    click Launcher "https://github.com/tsuno08/aimai/tree/main/bin/aimai"
    click CLI "https://github.com/tsuno08/aimai/blob/main/src/cli.py"
    click Controller "https://github.com/tsuno08/aimai/blob/main/src/controller.py"
    click Model "https://github.com/tsuno08/aimai/blob/main/src/model.py"
    click View "https://github.com/tsuno08/aimai/blob/main/src/view.py"

    classDef internal fill:#BEE3F8,stroke:#1E40AF;
    classDef external fill:#D1FAE5,stroke:#047857;
    classDef script fill:#E5E7EB,stroke:#374151;
```
