# waydotnet/zen-generator architecture

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

- Interactive diagram: https://gitdiagram.com/waydotnet/zen-generator
- Repository: https://github.com/waydotnet/zen-generator

## Overview

##### Project Type & Purpose
- This is a bidirectional code generator that converts between AsyncAPI 3.0 specifications and Python code. The project supports generating pure Python or FastAPI implementations from an AsyncAPI document and vice versa. The command-line interface (CLI) built on Typer lets users run commands like “fastapi”, “pure-python”, and “asyncapi-documentation” to perform these conversions.

##### Analyzing the File Structure
- Top-Level Files and Directories:
- .github: Contains GitHub workflows for CI/CD (e.g., python-publish.yml).
- LICENSE, README.md, pyproject.toml, .gitignore: Standard project files.
- asyncapi.yaml: A sample/specification file outlining the AsyncAPI structure.
- tests: Contains various test modules for verifying functionality.
- zen_generator: The main package holding the application logic.
∙ cli.py: Likely the entry point for the CLI.
∙ core: Contains submodules such as ast_utils, exception, formatting, io, parsing, and type_system – these modules manage the main business logic, utility functions, and error-handling.
∙ generators: Houses specific generator implementations for asyncapi, common Python, and python code generation.

##### Components
- CLI Interface:
- Command-line layer that accepts input (commands and options). This triggers specific generator functions.
- How the CLI parses the user-provided arguments and directs processing to the right generator.
- Core Module:
- Detail the “core” folder’s responsibilities: AST utilities for parsing and manipulating code, parsing functions for analyzing AsyncAPI specs, I/O modules for file operations, formatting, type system management, and custom exception handling.
- Generators:
- Three primary generator components – asyncapi, common_python, and python – each handling a specific conversion direction.
- That these generators both consume AsyncAPI specifications (input) and produce Python implementations (pure or FastAPI) and vice versa.
- Test Suite:
- Although not part of the runtime architecture, the tests directory indicates a structured approach to ensure each module’s correctness. You might model this as a quality assurance layer interacting with all other components.
- CI/CD and Dependency Management:
- A note for the CI part (.github/workflows) to indicate automated testing, linting (using Ruff), and publishing steps.
- External Tools:
- The integration with uv, pipx, and uvx for installation and command execution can be shown as user interactions with the system.

##### Relationships and Interactions
- The CLI (built with Typer) serves as the entry point for commands. It calls the corresponding functions in the generators.
- Each generator module, in turn, leverages the utilities provided in the core module (e.g., parsing AsyncAPI files, formatting outputs, type checking via type_system) to reliably convert between specifications and code.
- Error handling flows from generator functions to the CLI layer, where exceptions defined in the core/exception module manage failures.
- The testing suite interacts with all core and generator modules to simulate real-world usage by invoking these interactions.

##### Architectural Patterns & Principles
- Separation of Concerns: Clear division exists between CLI input handling, core utility logic (e.g., parsing, formatting), and conversion logic implemented in the generator modules.
- Modularity: Each module in the core and generators packages is designed to be as independent as possible, aiding testing and future enhancements.
- Bidirectional Conversion: The code architecture is built to support both directions—from AsyncAPI specification to Python code and vice versa.
- Extensibility: The folder structure and command modularization (via Typer) allow for future expansion, such as adding new types of code outputs or specifications.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Interface Layer"
        CLI("CLI Interface"):::cli
        External("External Tools (uv, pipx, uvx)"):::external
    end

    subgraph "Generators"
        AsyncAPI("AsyncAPI Conversion"):::generator
        CommonPython("Common Python Conversion"):::generator
        PythonConv("Python Conversion"):::generator
    end

    subgraph "Core Module"
        AST("AST Utilities"):::core
        Exception("Exception Handling"):::core
        Formatting("Formatting Utilities"):::core
        IO("I/O Operations"):::core
        Parsing("Parsing Functions"):::core
        TypeSys("Type System Management"):::core
    end

    Test("Test Suite"):::test
    CI("CI/CD Workflows"):::ci

    External -->|"installs/executes"| CLI
    CLI -->|"asyncapi-documentation"| AsyncAPI
    CLI -->|"pure-python"| CommonPython
    CLI -->|"fastapi"| PythonConv

    AsyncAPI -->|"parses"| Parsing
    AsyncAPI -->|"handles_I/O"| IO

    CommonPython -->|"formats"| Formatting
    CommonPython -->|"handles_I/O"| IO

    PythonConv -->|"checks_types"| TypeSys
    PythonConv -->|"handles_I/O"| IO

    Exception -->|"error_handling"| CLI

    Test -->|"integration_tests"| CLI
    Test -->|"unit_tests"| AsyncAPI
    Test -->|"unit_tests"| CommonPython
    Test -->|"unit_tests"| PythonConv
    Test -->|"unit_tests"| AST
    Test -->|"unit_tests"| Parsing

    CI -->|"runs_tests"| Test

    click CLI "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/cli.py"
    click AST "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/core/ast_utils.py"
    click Exception "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/core/exception.py"
    click Formatting "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/core/formatting.py"
    click IO "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/core/io.py"
    click Parsing "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/core/parsing.py"
    click TypeSys "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/core/type_system.py"
    click AsyncAPI "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/generators/asyncapi.py"
    click CommonPython "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/generators/common_python.py"
    click PythonConv "https://github.com/waydotnet/zen-generator/blob/main/zen_generator/generators/python.py"
    click Test "https://github.com/waydotnet/zen-generator/tree/main/tests"
    click CI "https://github.com/waydotnet/zen-generator/tree/main/.github/workflows"

    classDef cli fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef external fill:#cccccc,stroke:#000,stroke-width:2px;
    classDef generator fill:#ffcc80,stroke:#000,stroke-width:2px;
    classDef core fill:#caffbf,stroke:#000,stroke-width:2px;
    classDef test fill:#ffeb99,stroke:#000,stroke-width:2px;
    classDef ci fill:#d0bfff,stroke:#000,stroke-width:2px;
```
