# typelate/muxt architecture

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

- Interactive diagram: https://gitdiagram.com/typelate/muxt
- Repository: https://github.com/typelate/muxt

## Overview

##### Project type and purpose
- Muxt is a standalone, open-source code-generation CLI tool written in Go.
- Its purpose is to scan Go HTML templates, extract HTTP route definitions from their names, analyze matching Go receiver methods, and emit strongly-typed HTTP handlers without runtime reflection.

##### File structure
- Top-level “cmd/muxt” directory: CLI entry point and its tests.
- “internal/cli”: flag parsing, command registration, help text.
- “internal/muxt”: core orchestration of scanning, validation, code generation.
- “internal/asteval”: template evaluation and validation logic.
- “internal/astgen”: AST-based Go code generator.
- “internal/asterr”: error-wrapping utilities.
- “docs”, “examples” and “tests” are documentation and usage samples—supporting but not part of runtime.
- Configuration files (go.mod, Go workflows) and license/legal files.

##### README for additional insights
- The README describes a single CLI command (`muxt generate`) that drives the pipeline.
- Emphasizes a compile-time type-checking approach using `go/types`, `html/template`, and no runtime reflection.
- Illustrates how templates define request patterns, status codes, and calls into user-provided methods.

##### Detail without overthinking
- Every major module—even small ones (e.g., `internal/asterr`)—to show full architecture.
- Keep components coarse enough to avoid clutter but fine-grained enough to reflect the separate responsibilities.
- How the user’s templates and methods plug into the pipeline and how generated handlers feed back into the user application.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Developer(["Developer"]):::external
    CLI["CLI Front-End"]:::frontend
    Orchestration["Core Orchestration"]:::analysis
    TemplateLoader["Template Loader"]:::analysis
    SignatureAnalyzer["Signature Analyzer"]:::analysis
    Validator["Validator"]:::analysis
    ErrorUtils["Error-Wrapping Utilities"]:::analysis
    ASTGen["AST Generator"]:::codegen
    CodeWriter["Code Formatter & Writer"]:::codegen
    GeneratedCode(["Generated Go Code"]):::external

    Developer -->|"invokes muxt generate"| CLI
    CLI -->|"orchestrates pipeline"| Orchestration
    Orchestration -->|"loads templates"| TemplateLoader
    TemplateLoader -->|"passes AST"| SignatureAnalyzer
    SignatureAnalyzer -->|"type & method metadata"| Validator
    Validator -->|"validated metadata"| ASTGen
    ASTGen -->|"AST nodes"| CodeWriter
    CodeWriter -->|"writes .go files"| GeneratedCode
    SignatureAnalyzer -->|"wrap errors via"| ErrorUtils
    Validator -->|"uses error utils"| ErrorUtils

    click CLI "https://github.com/typelate/muxt/blob/main/cmd/muxt/main.go"
    click CLI "https://github.com/typelate/muxt/blob/main/internal/cli/commands.go"
    click CLI "https://github.com/typelate/muxt/blob/main/internal/cli/help.txt"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/check.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/documentation.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/routes.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/template.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/template_data.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/template_route_path.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/validation_generate.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/validation_html.go"
    click Orchestration "https://github.com/typelate/muxt/blob/main/internal/muxt/name.go"
    click TemplateLoader "https://github.com/typelate/muxt/blob/main/internal/asteval/template.go"
    click TemplateLoader "https://github.com/typelate/muxt/blob/main/internal/asteval/reflect.go"
    click TemplateLoader "https://github.com/typelate/muxt/blob/main/internal/asteval/string.go"
    click SignatureAnalyzer "https://github.com/typelate/muxt/blob/main/internal/asteval/reflect.go"
    click SignatureAnalyzer "https://github.com/typelate/muxt/blob/main/internal/asteval/template_internal_test.go"
    click Validator "https://github.com/typelate/muxt/blob/main/internal/asteval/template.go"
    click Validator "https://github.com/typelate/muxt/blob/main/internal/asteval/string.go"
    click Validator "https://github.com/typelate/muxt/blob/main/internal/muxt/check.go"
    click Validator "https://github.com/typelate/muxt/blob/main/internal/muxt/validation_generate.go"
    click Validator "https://github.com/typelate/muxt/blob/main/internal/muxt/validation_html.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/gen.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/http.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/call.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/cmp.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/bytes.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/errors.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/format.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/literals.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/queries.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/slog.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/strconv.go"
    click ASTGen "https://github.com/typelate/muxt/blob/main/internal/astgen/time.go"
    click CodeWriter "https://github.com/typelate/muxt/blob/main/internal/muxt/file.go"
    click CodeWriter "https://github.com/typelate/muxt/blob/main/internal/muxt/file_internal_test.go"
    click ErrorUtils "https://github.com/typelate/muxt/blob/main/internal/asterr/wrap.go"

    classDef frontend fill:#e0f0ff,stroke:#0366d6,color:#0366d6
    classDef analysis fill:#e6ffed,stroke:#28a745,color:#22863a
    classDef codegen fill:#fff5b1,stroke:#d73a49,color:#d73a49
    classDef external fill:#f6f8fa,stroke:#333,color:#333
```
