# nicomyerr/totorosay architecture

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

- Interactive diagram: https://gitdiagram.com/nicomyerr/totorosay
- Repository: https://github.com/nicomyerr/totorosay

## Overview

- **CLI Front Door (binary)**: argument parsing, choosing options (`--big`), calling library functions, writing to stdout.
- **Core Rendering Library**: text wrapping / layout, bubble generation, selecting the Totoro template, assembling final output.
- **Embedded resources**: ASCII art templates (small + big) stored under `resources/`.
- **Tests**: validate wrapping/formatting behavior using fixed input files.

##### What the file tree tells you about architecture
Key structural signals:

- `Cargo.toml`, `Cargo.lock`: standard Rust crate. Likely one package producing both lib + bin.
- `src/main.rs`: binary entrypoint (`totorosay` command).
- `src/lib.rs`: reusable library API (core logic).
- `resources/totoro.txt`, `resources/totoro-big.txt`: static ASCII art templates (inputs to renderer).

No network, no DB, no external services. Primary external dependency is the **terminal/stdout**.

##### What the README adds (behavioral requirements to reflect)
From README:
- Command: `totorosay Hello world!`
- Flag: `-b` / `--big` uses big Totoro
- Output: “Totoro says …” (speech bubble + totoro art)
- Install method: `cargo install ...`

- **CLI args** → **mode selection** (small/big) → **render pipeline** → **stdout**

##### User / Terminal
- User enters command with arguments
- Receives rendered ASCII output

##### Binary: `totorosay` (`src/main.rs`)
- Responsibility: parse CLI args, convert to “render request”, call library, print result
- Inputs: argv, stdin (likely none), environment (terminal width might be relevant if implemented)
- Output: stdout

##### Library crate (`src/lib.rs`)
- **Argument/Options Model** (big vs small, text input) — even if represented as structs
- **Text normalization** (handle embedded line breaks, multiple spaces, etc.)
- **Line wrapping / layout engine** (many test fixtures strongly imply wrapping rules)
- **Speech bubble generator** (adds borders/format around wrapped lines)
- **Totoro template loader/selector**
- Select small template (`resources/totoro.txt`) or big (`resources/totoro-big.txt`)
- **Renderer/Composer**
- Combines bubble + chosen Totoro into final string

##### Resources
- `resources/totoro.txt`
- `resources/totoro-big.txt`
Them as “static assets” consumed by the library.

##### Tests
- `tests/lib_test.rs` (test runner)
- `tests/resources/*` (fixture files)
Tests as a separate boundary that exercises the library.

##### Library → Resources
- Whether it’s runtime file I/O or compile-time embedding (annotate as “File read” unless you confirm `include_str!`).

##### Architectural patterns/design principles used

- **Separation of concerns**: `main.rs` (I/O + CLI) vs `lib.rs` (pure rendering logic). This is a strong, deliberate boundary.
- **Pipeline architecture** inside the library: normalize → wrap → bubble → select template → compose.
- **Test-driven/fixture-driven validation**: many fixture files imply careful handling of edge cases (line breaks, single long words, etc.).

##### Relevant technologies
- Language: **Rust**
- Build tool: **Cargo**
- Runtime environment: **Terminal / stdout**
- CI: **GitHub Actions**
- leave it as “CLI arg parsing (crate TBD)”, or
- open `Cargo.toml` to confirm and then label precisely.

##### Clear labels
Use explicit names that map to repo artifacts:
- “`totorosay` binary (src/main.rs)”
- “Rendering library (src/lib.rs)”
- “Small template (resources/totoro.txt)”
- “Big template (resources/totoro-big.txt)”
- “Integration tests (tests/lib_test.rs)”

- “argv text”
- “RenderRequest”
- “String output”
- “Template content”
- “Fixture input”

##### User/Terminal
→ 2. `totorosay` (main.rs)
→ 3. Library pipeline (normalize → wrap → bubble → template select → compose)
↘ loads templates from Resources
→ back to `totorosay`
→ stdout to Terminal

- `cargo test` runs `tests/lib_test.rs`
- reads `tests/resources/*`
- calls into library

**CI lane (optional):**
- GitHub Actions triggers `cargo test` on push/PR

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= Runtime =========
    subgraph "Runtime (Local Machine Process)"
        direction TB

        User["User"]:::external
        Term["Terminal (stdout)"]:::external

        Bin(("totorosay CLI\nBinary Entrypoint")):::runtime

        subgraph "Core Rendering Library (crate)"
            direction TB

            Lib["Public API Surface\n(render request -> string)"]:::library

            subgraph "Render Pipeline (pure logic)"
                direction TB
                Opts["Options/Model\n(size=Small|Big, text)"]:::library
                Norm["Text Normalization\n(spaces/linebreaks)"]:::library
                Wrap["Line Wrapping / Layout Engine"]:::library
                Bubble["Speech Bubble Generator\n(borders + padding)"]:::library
                TSel["Totoro Template Selector"]:::library
                Compose["Renderer/Composer\n(bubble + totoro)"]:::library
            end
        end

        subgraph "Embedded Resources (Static Assets)"
            direction TB
            ResSmall[/"Small Totoro Template\n(totoro.txt)"/]:::resource
            ResBig[/"Big Totoro Template\n(totoro-big.txt)"/]:::resource
        end

        User -->|"argv:command+flags+text"| Bin
        Bin -->|"RenderRequest{text,size}"| Lib
        Lib -->|"configure"| Opts
        Opts -->|"text"| Norm
        Norm -->|"normalized_lines"| Wrap
        Wrap -->|"wrapped_lines"| Bubble
        Bubble -->|"bubble_block"| TSel
        TSel -->|"load_template"| ResSmall
        TSel -->|"load_template"| ResBig
        TSel -->|"template_content"| Compose
        Bubble -->|"bubble_block"| Compose
        Compose -->|"RenderedOutput:String"| Lib
        Lib -->|"RenderedOutput:String"| Bin
        Bin -->|"print(rendered_string)"| Term
        Term -->|"display"| User
    end

    %% ========= Tests =========
    subgraph "Tests (cargo test)"
        direction TB

        TestRunner["Integration/Library Tests\n(tests/lib_test.rs)"]:::test

        subgraph "Test Fixtures (files)"
            direction TB
            TResDir[/"tests/resources/ (fixtures dir)"/]:::testres
            Fix1[/"totorosay-big-single-word.txt"/]:::testres
            Fix2[/"totorosay-linebreak.txt"/]:::testres
            Fix3[/"totorosay-max-single-line-single-word.txt"/]:::testres
            Fix4[/"totorosay-multiple-linebreaks.txt"/]:::testres
            Fix5[/"totorosay-single-word.txt"/]:::testres
        end

        TestRunner -->|"read_fixtures"| TResDir
        TResDir -->|"fixture_input"| Fix1
        TResDir -->|"fixture_input"| Fix2
        TResDir -->|"fixture_input"| Fix3
        TResDir -->|"fixture_input"| Fix4
        TResDir -->|"fixture_input"| Fix5

        TestRunner -->|"call_library_API\n(assert_output_matches)"| Lib
    end

    %% ========= CI =========
    subgraph "Build & CI (Delivery Pipeline)"
        direction TB
        CI["GitHub Actions Workflow\nRust CI"]:::ci
        Cargo["Cargo\n(fmt/clippy/test/build)"]:::ci
        CI -->|"runs"| Cargo
        Cargo -->|"executes"| TestRunner
    end

    %% ========= Click Events (from mapping) =========
    click Bin "https://github.com/nicomyerr/totorosay/blob/main/src/main.rs"
    click Lib "https://github.com/nicomyerr/totorosay/blob/main/src/lib.rs"
    click ResSmall "https://github.com/nicomyerr/totorosay/blob/main/resources/totoro.txt"
    click ResBig "https://github.com/nicomyerr/totorosay/blob/main/resources/totoro-big.txt"
    click TestRunner "https://github.com/nicomyerr/totorosay/blob/main/tests/lib_test.rs"
    click TResDir "https://github.com/nicomyerr/totorosay/tree/main/tests/resources/"
    click Fix1 "https://github.com/nicomyerr/totorosay/blob/main/tests/resources/totoro-big-single-word.txt"
    click Fix2 "https://github.com/nicomyerr/totorosay/blob/main/tests/resources/totoro-linebreak.txt"
    click Fix3 "https://github.com/nicomyerr/totorosay/blob/main/tests/resources/totoro-max-single-line-single-word.txt"
    click Fix4 "https://github.com/nicomyerr/totorosay/blob/main/tests/resources/totoro-multiple-linebreaks.txt"
    click Fix5 "https://github.com/nicomyerr/totorosay/blob/main/tests/resources/totoro-single-word.txt"
    click CI "https://github.com/nicomyerr/totorosay/blob/main/.github/workflows/rust-ci.yaml"

    %% ========= Styles =========
    classDef external fill:#E8F1FF,stroke:#2B5FB8,stroke-width:1.5px,color:#0B1B3A;
    classDef runtime fill:#D7ECFF,stroke:#1E4E8C,stroke-width:2px,color:#0B1B3A;
    classDef library fill:#DFF7E6,stroke:#2B7A3D,stroke-width:1.5px,color:#0B2A14;
    classDef resource fill:#FFE8CC,stroke:#B56A00,stroke-width:1.5px,color:#3A2200;
    classDef test fill:#EFEFF4,stroke:#5B5B6A,stroke-width:1.5px,color:#1C1C24;
    classDef testres fill:#F6F6FA,stroke:#7A7A8A,stroke-width:1.2px,color:#1C1C24;
    classDef ci fill:#F3E8FF,stroke:#6B2FB8,stroke-width:1.5px,color:#1F0B3A;
```
