# stephenbuttolph/canoto architecture

> Architecture diagram of the GitHub repository stephenbuttolph/canoto, 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/stephenbuttolph/canoto
- Repository: https://github.com/stephenbuttolph/canoto

## Overview

##### Main Components
- CLI / Command-Line Interface: Represented by the “canoto” executable (e.g., canoto.go, the canoto folder containing main.go, and the other command files). This is the entry point for users to run code generation.
- Code Generation Engine (“generate” package): Contains the files in the generate/ directory. This module parses Go source files for message definitions, analyzes struct tags, and auto-generates supporting code (.canoto.go and possibly .proto files). Also include the internal generation files under internal/ if applicable.
- Core Library: The heart of Canoto’s serialization capabilities. This includes core types and interfaces (Message, Field, FieldMaker) implemented in the main files (like canoto.canoto.go) and further supported by the internal/ directory. It is responsible for marshaling, unmarshaling, caching sizes (via the cached canotoData), and providing the canonical representation.
- Internal Utilities and Protocol Support: The “internal” directory houses protocol-related implementations (such as internal/pb with the generated protocol buffer files, as well as additional support like the inlined serialization variants). These utilities help ensure that serialization is both canonical and compatible with Protocol Buffers.
- Testing and Fuzzing Components: Present in internal/testdata and testdata/fuzz. These modules are used to verify and stress-test the serialization and code generation logic. They often contain examples of error conditions (duplicate fields, invalid numbers, etc.) which ensure correctness.
- CI/CD & Automation: Although not part of the runtime architecture, the .github/workflows files indicate automated testing, linting, and benchmarking pipelines that validate the quality of the code and the generated artifacts.

##### Relationships and Data Flow
- User Input / Go Source Files: Developers define their messages as Go structs (with the canoto tags) in their source files.
- Code Generation Step: The CLI (invoked directly or via go:generate) takes these source files and calls the code generation engine. This engine parses the struct definitions, inspects tags, and generates additional files (.canoto.go and optionally .proto files) that include precomputed size caches and implementations of the Message, Field, and FieldMaker interfaces.
- Core Library Interaction: Both the CLI and generated code rely on the core library which implements serialization/deserialization logic, ensuring that the output messages are fast, compact, canonical, and backwards compatible.
- CI/CD Pipeline: The GitHub workflows automatically trigger builds, tests, and linting upon changes to the repository, ensuring integration and quality.

##### Architectural Patterns and Design Principles
- Modular Design: The separation into directories (canoto, generate, internal, testdata) emphasizes a clear separation of concerns: the library API, the code generation tool, testing, and supporting internal implementations.
- Code Generation Pattern: A key principle is that source files are extended and enhanced automatically through code generation. This pattern is central to how Canoto minimizes boilerplate and enables consistency.
- Interface-driven Design: Use of well-defined interfaces (Message, Field, FieldMaker) abstracts the serialization details and allows for both value and pointer based implementations, as well as future extensibility.
- Concurrency-safe Techniques: The documentation refers to atomic variables and strategies (or avoiding them with noatomic) for thread safe operations, indicating concurrent safe design considerations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    subgraph "User Input"
        U("User/Go Source Files"):::user
    end

    %% CLI Interface
    subgraph "CLI Interface"
        CLI1("CLI: canoto.go"):::cli
        CLI2("CLI: main.go"):::cli
    end

    %% Code Generation Engine
    subgraph "Generation Engine"
        GEN("Generate Module"):::generation
    end

    %% Generated Code
    subgraph "Generated Code"
        GC("Generated Code (.canoto.go, .proto)"):::generated
    end

    %% Core Library
    subgraph "Core Library"
        CORE("Core Serialization Library"):::core
    end

    %% Internal Utilities and Protocol Support
    subgraph "Internal Protocol Support"
        INT("Internal Protocol Buffers & Inlined Serialization"):::internal
    end

    %% Testing & Fuzzing
    subgraph "Testing & Fuzzing"
        TEST("Testing & Fuzzing Modules"):::testing
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CICD("CI/CD Pipeline"):::cicd
    end

    %% Data Flow Connections
    U -->|"providesGoStructs"| CLI1
    U -->|"providesGoStructs"| CLI2
    CLI1 -->|"invokesGeneration"| GEN
    CLI2 -->|"invokesGeneration"| GEN
    GEN -->|"generatesCode"| GC
    GC -->|"integratesWith"| CORE
    CORE -->|"utilizes"| INT
    TEST -->|"validatesSerialization"| CORE

    %% CI/CD triggering build and tests
    CICD ---|"triggersBuildTestLint"| CLI1
    CICD ---|"triggersBuildTestLint"| GEN
    CICD ---|"triggersBuildTestLint"| CORE
    CICD ---|"triggersBuildTestLint"| TEST

    %% Click Events for CLI / Command-Line Interface
    click CLI1 "https://github.com/stephenbuttolph/canoto/blob/main/canoto.go"
    click CLI2 "https://github.com/stephenbuttolph/canoto/blob/main/canoto/main.go"

    %% Click Event for Code Generation Engine
    click GEN "https://github.com/stephenbuttolph/canoto/tree/main/generate"

    %% Click Events for Core Library
    click CORE "https://github.com/stephenbuttolph/canoto/blob/main/canoto.canoto.go"
    click CORE "https://github.com/stephenbuttolph/canoto/blob/main/canoto.canoto_test.go"
    click CORE "https://github.com/stephenbuttolph/canoto/blob/main/internal/canoto.go"
    click CORE "https://github.com/stephenbuttolph/canoto/blob/main/internal/canoto.canoto.go"

    %% Click Events for Internal Utilities and Protocol Support
    click INT "https://github.com/stephenbuttolph/canoto/tree/main/internal/pb"
    click INT "https://github.com/stephenbuttolph/canoto/blob/main/internal/inlined_canoto.go"
    click INT "https://github.com/stephenbuttolph/canoto/blob/main/internal/inlined_canoto.canoto.go"

    %% Click Events for Testing and Fuzzing Components
    click TEST "https://github.com/stephenbuttolph/canoto/tree/main/internal/testdata"
    click TEST "https://github.com/stephenbuttolph/canoto/tree/main/internal/testdata/fuzz"
    click TEST "https://github.com/stephenbuttolph/canoto/tree/main/testdata/fuzz"

    %% Click Event for CI/CD & Automation
    click CICD "https://github.com/stephenbuttolph/canoto/tree/main/.github/workflows"

    %% Styles
    classDef user fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef cli fill:#ffa07a,stroke:#000,stroke-width:2px;
    classDef generation fill:#ffdab9,stroke:#000,stroke-width:2px;
    classDef generated fill:#ffdab9,stroke:#000,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef internal fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef testing fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef cicd fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
