# lukeautry/tsoa architecture

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

- Interactive diagram: https://gitdiagram.com/lukeautry/tsoa
- Repository: https://github.com/lukeautry/tsoa

## Overview

##### Main Components

a. Core Components:
- CLI Package (Command Line Interface)
- Runtime Package
- Main TSOA Package
- Framework Integration Layer (Express, Hapi, Koa)

b. Key Processing Components:
- Metadata Generation System
- Route Generation System
- Swagger/OpenAPI Spec Generation
- Decorator System

**┌─ Input Layer ─────────────────────────────┐**
- TypeScript Controllers & Decorators        │
- ┬─────────────────────┘
- ↓
**┌─ Processing Layer ────────────────────────┐**
- ┌─────────────────┐  ┌─────────────────┐ │
- Metadata         │  │Route            │ │
- Generation       │←→│Generation       │ │
- ┘  └─────────────────┘ │
- ┌─────────────────┐  ┌─────────────────┐ │
- Swagger/OpenAPI  │  │Template         │ │
- Generation       │  │Processing       │ │
- ┘  └─────────────────┘ │
- ┬─────────────────────┘
- ↓
**┌─ Output Layer ──────────────────────────┐**
- ┌─────────────┐ ┌────────┐ ┌─────────┐ │
- Express      │ │Hapi    │ │Koa      │ │
- Routes       │ │Routes  │ │Routes   │ │
- ┘ └────────┘ └─────────┘ │
- ┘

##### Key Relationships

a. Data Flow:
- TypeScript controllers → Metadata Generation
- Metadata → Route Generation
- Metadata → Swagger/OpenAPI Spec Generation
- Route Generation → Framework-specific routes

b. Dependencies:
- How the CLI package orchestrates the process
- How the Runtime package provides core functionality
- Demonstrate framework adapter relationships

##### Important Subsystems to Detail

a. Metadata Generation:
- Controller Generator
- Method Generator
- Parameter Generator
- Type Resolution System

b. Route Generation:
- Template System
- Framework-specific adapters
- Middleware handling

c. Swagger/OpenAPI Generation:
- Spec Generator (v2 & v3)
- Schema Generation
- Path Generation

##### Additional Elements

- Version compatibility information
- Configuration flow
- Test coverage and validation points

##### Implementation Details

Use standardized UML or C4 notation:
- Diamonds for aggregation relationships

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        TS[TypeScript Controllers]
        DEC[Decorator System]:::decorator
    end

    subgraph Processing
        subgraph MetadataGen[Metadata Generation]
            CG[Controller Generator]:::metadata
            MG[Method Generator]:::metadata
            PG[Parameter Generator]:::metadata
        end

        subgraph RouteGen[Route Generation]
            RG[Route Generator]:::route
            TEMP[Templates]:::route
        end

        subgraph SwaggerGen[Swagger/OpenAPI Generation]
            SG2[Spec Generator v2]:::swagger
            SG3[Spec Generator v3]:::swagger
        end
    end

    subgraph Output
        subgraph Frameworks
            EXP[Express Routes]:::framework
            HAPI[Hapi Routes]:::framework
            KOA[Koa Routes]:::framework
        end
        SPEC[OpenAPI Specification]:::output
    end

    subgraph Packages
        CLI[CLI Package]:::package
        RT[Runtime Package]:::package
        TSOA[Main TSOA Package]:::package
    end

    %% Relationships
    TS --> MetadataGen
    DEC --> MetadataGen
    MetadataGen --> RouteGen
    MetadataGen --> SwaggerGen
    RouteGen --> Frameworks
    SwaggerGen --> SPEC
    CLI --> MetadataGen
    CLI --> RouteGen
    CLI --> SwaggerGen
    RT --> DEC
    TSOA --> RT
    TSOA --> CLI

    %% Click Events
    click CLI "https://github.com/lukeautry/tsoa/tree/master/packages/cli"
    click RT "https://github.com/lukeautry/tsoa/tree/master/packages/runtime"
    click TSOA "https://github.com/lukeautry/tsoa/tree/master/packages/tsoa"
    click EXP "https://github.com/lukeautry/tsoa/tree/master/packages/runtime/src/routeGeneration/templates/express"
    click HAPI "https://github.com/lukeautry/tsoa/tree/master/packages/runtime/src/routeGeneration/templates/hapi"
    click KOA "https://github.com/lukeautry/tsoa/tree/master/packages/runtime/src/routeGeneration/templates/koa"
    click CG "https://github.com/lukeautry/tsoa/blob/master/packages/cli/src/metadataGeneration/controllerGenerator.ts"
    click MG "https://github.com/lukeautry/tsoa/blob/master/packages/cli/src/metadataGeneration/methodGenerator.ts"
    click PG "https://github.com/lukeautry/tsoa/blob/master/packages/cli/src/metadataGeneration/parameterGenerator.ts"
    click RG "https://github.com/lukeautry/tsoa/blob/master/packages/cli/src/routeGeneration/routeGenerator.ts"
    click TEMP "https://github.com/lukeautry/tsoa/tree/master/packages/cli/src/routeGeneration/templates"
    click SG2 "https://github.com/lukeautry/tsoa/blob/master/packages/cli/src/swagger/specGenerator2.ts"
    click SG3 "https://github.com/lukeautry/tsoa/blob/master/packages/cli/src/swagger/specGenerator3.ts"
    click DEC "https://github.com/lukeautry/tsoa/tree/master/packages/runtime/src/decorators"

    %% Styling
    classDef package fill:#f9f,stroke:#333,stroke-width:2px
    classDef metadata fill:#aaf,stroke:#333
    classDef route fill:#afa,stroke:#333
    classDef swagger fill:#faa,stroke:#333
    classDef framework fill:#ffa,stroke:#333
    classDef output fill:#ddd,stroke:#333
    classDef decorator fill:#f8f,stroke:#333

    %% Legend
    subgraph Legend
        P[Package]:::package
        M[Metadata Component]:::metadata
        R[Route Component]:::route
        S[Swagger Component]:::swagger
        F[Framework Component]:::framework
        O[Output]:::output
        D[Decorator]:::decorator
    end
```
