# chivier/lanno architecture

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

- Interactive diagram: https://gitdiagram.com/chivier/lanno
- Repository: https://github.com/chivier/lanno

## Overview

##### Project Type and Purpose
- Lanno is a CLI tool for annotating and documenting files.
- It is built in Go, as indicated by go.mod, go.sum, and main.go.
- Its main functions revolve around reading file metadata, processing annotations, managing tags/descriptions, and providing an interactive file browser.

##### Analyzing the File Structure
- Top-Level Files and Directories:
- main.go: The entry point that handles command-line input and calls appropriate functions.
- internal/ directory: Contains core modules. For instance:
▪ internal/file_stat/file_stat.go – handles file statistics (retrieving metadata from files, file info calculations).
▪ internal/table/table.go – manages the formatting and display of file data in a tabular form.
- .github/workflows: Contains CI pipeline configurations (e.g., go.yml) that ensure code quality through automated tests/buils.
- test/ directory: Contains tests for components like file_stat.
- design_doc.md: Likely elaborates on design decisions and architectural strategies.
- image/: Contains assets like logos and sample images used in the README.
- Configuration files (go.mod, go.sum) denote dependency management.

##### Key Components
a. CLI Interface & Command Parser (main.go):
- Represents the starting point of the tool.
- Directs commands to sub-components based on user input.
b. Annotation & Metadata Manager:
- Although not explicitly a package, this conceptual module encompasses the reading, tagging, and description logic.
- Interacts with a persistent storage file (.lanno.json) for saving metadata.
c. Internal Modules:
- FileStat Module (internal/file_stat): Responsible for scanning and retrieving file statistics.
- Table Module (internal/table): Responsible for rendering output data in a formatted table for CLI display.
d. Data Storage:
- .lanno.json (as described in the README) is the file that holds the persistent annotation metadata.
e. CI/CD Pipeline:
- The GitHub workflows (like go.yml) that automate testing, building, and possibly packaging the tool.
f. External Interactions:
- User’s file system: The tool reads directories/files and writes to .lanno.json.

##### Relationships and Interactions
- The CLI interface accepts user commands and parses those commands.
- It calls the Annotation Manager to either view, add, or remove tags/descriptions.
- The FileStat module is invoked to gather stats on files (file details, counts, etc.) before annotations are processed.
- The Table module then formats and displays the processed information to the user.
- The tool reads from and writes back to the local metadata store (.lanno.json) to persist changes.
- The CI pipeline runs tests and builds the tool whenever changes are pushed, ensuring high code reliability.

##### Architectural Patterns and Principles
- Modular design: Separation of concerns is clear—each internal package handles distinct functionality.
- Single-responsibility: Modules like file_stat and table are focused on their own tasks.
- Clean CLI design: The command-line interface is designed to map user commands directly to backend actions.
- CI integration: Automated workflows support continuous delivery and high-quality development.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Interaction"
        user["User Input (CLI)"]:::ui
    end

    user -->|"initiates"| cli["CLI Command Parser (main.go)"]:::cli
    cli -->|"processes"| annot["Annotation & Metadata Manager"]:::biz
    annot -->|"gathers stats"| fs["FileStat Module (internal/file_stat)"]:::module
    annot -->|"formats output"| table["Table Renderer (internal/table)"]:::module
    annot -->|"reads/writes"| meta["Metadata Storage (.lanno.json)"]:::persistence
    annot -->|"displays"| out["CLI Output Display"]:::ui

    subgraph "Supporting Components"
        ci["CI/CD Pipeline (.github/workflows/go.yml)"]:::support
        doc["Design Documentation (design_doc.md)"]:::support
    end

    click cli "https://github.com/chivier/lanno/blob/main/main.go"
    click fs "https://github.com/chivier/lanno/blob/main/internal/file_stat/file_stat.go"
    click table "https://github.com/chivier/lanno/blob/main/internal/table/table.go"
    click ci "https://github.com/chivier/lanno/blob/main/.github/workflows/go.yml"
    click doc "https://github.com/chivier/lanno/blob/main/design_doc.md"

classDef ui fill:#fdf6e3,stroke:#657b83,stroke-width:2px;
classDef cli fill:#eee8d5,stroke:#586e75,stroke-width:2px;
classDef biz fill:#b58900,stroke:#073642,stroke-width:2px,fill-opacity:0.3;
classDef module fill:#268bd2,stroke:#002b36,stroke-width:2px,fill-opacity:0.3;
classDef persistence fill:#cb4b16,stroke:#002b36,stroke-width:2px,fill-opacity:0.3;
classDef support fill:#2aa198,stroke:#073642,stroke-width:2px,fill-opacity:0.3;
```
