# naomis/router architecture

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

## Overview

##### Main Components
- Core Module: Under src/core, you have components such as MetadataStorage.ts, MethodDecoratorFactory.ts, and RouterRegistry.ts. This module is responsible for handling metadata extraction from decorator usage, constructing the route mappings, and registering them with the Express application.
- Decorators: The module under src/decorators contains individual decorators like Controller.ts, Get.ts, Post.ts, Delete.ts, and Put.ts. These encapsulate the logic for annotating classes and methods.
- Utilities: The src/utils folder (with, for instance, types.ts) holds utility functions or type definitions used across the library.
- Examples: The examples folder provides a sample Usage scenario, including a sample controller and server setup, which illustrates how a consumer would integrate the library with Express.
- Tests: The tests folder includes unit/integration tests that validate the functionality of the API, especially regarding how routes are set up.

##### Relationships and Interactions
- The decorators (from src/decorators) are applied to user-defined classes and methods to capture necessary metadata.
- Metadata Storage in the Core module collects this data.
- The Router Registry then reads this metadata and dynamically registers the routes with an Express application.
- The examples simulate how these components interact, while tests ensure expected interactions and behavior.

##### Important Architectural Patterns
- Separation of Concerns: The design clearly separates route annotation (decorators) from route registration (RouterRegistry) and metadata handling (MetadataStorage).
- Decorator Pattern: Utilization of TypeScript decorators abstracts routing logic from business logic.
- Configuration-driven Registration: Passing options (like API prefixes and middlewares) to the RouterRegistry to integrate routes into Express.

##### Relevant Technologies and Frameworks
- Node.js as the runtime environment.
- Express.js for HTTP server functionalities.
- TypeScript for type safety and use of decorators.
- Testing with Jest.
- GitHub Actions for CI/CD support (as seen in the .github/workflows directory).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Decorators Layer
    subgraph "Decorator Layer"
        D_Controller["Controller (Decorator)"]
        D_Get["Get (Decorator)"]
        D_Post["Post (Decorator)"]
        D_Delete["Delete (Decorator)"]
        D_Put["Put (Decorator)"]
    end

    %% Core Infrastructure
    subgraph "Core Infrastructure"
        C_MetadataStorage["MetadataStorage"]
        C_MethodFactory["MethodDecoratorFactory"]
        C_RouterRegistry["RouterRegistry"]
    end

    %% Utilities
    U_Utils["Types & Utils"]

    %% Examples
    subgraph "Examples"
        E_UserController["UserController"]
        E_Server["SampleServer"]
    end

    %% Tests
    subgraph "Tests"
        T_ApiController["API Controller Test"]
        T_ApiTest["API Test"]
        T_IndexTest["Index Test"]
    end

    %% Express Application
    ExpressApp["Express Application"]

    %% Arrows: Flow of control and data
    E_UserController -->|"annotates"| D_Controller

    D_Controller -->|"captures_metadata"| C_MetadataStorage
    D_Get -->|"captures_metadata"| C_MetadataStorage
    D_Post -->|"captures_metadata"| C_MetadataStorage
    D_Delete -->|"captures_metadata"| C_MetadataStorage
    D_Put -->|"captures_metadata"| C_MetadataStorage

    C_MethodFactory -->|"supports"| C_MetadataStorage
    U_Utils -->|"supports"| C_MetadataStorage

    C_MetadataStorage -->|"provides_metadata"| C_RouterRegistry
    C_RouterRegistry -->|"registers_routes"| ExpressApp

    E_Server -->|"launches"| ExpressApp

    T_ApiTest -->|"validates"| C_RouterRegistry
    T_ApiController -->|"validates"| C_RouterRegistry
    T_IndexTest -->|"validates"| C_RouterRegistry

    %% Styles
    class D_Controller,D_Get,D_Post,D_Delete,D_Put decorators;
    class C_MetadataStorage,C_MethodFactory,C_RouterRegistry core;
    class U_Utils utils;
    class E_UserController,E_Server examples;
    class T_ApiController,T_ApiTest,T_IndexTest tests;
    class ExpressApp express;

    %% Class Definitions
    classDef decorators fill:#ccf,stroke:#333,stroke-width:2px;
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef utils fill:#fcf,stroke:#333,stroke-width:2px;
    classDef examples fill:#ffc,stroke:#333,stroke-width:2px;
    classDef tests fill:#ffa,stroke:#333,stroke-width:2px;
    classDef express fill:#cfc,stroke:#333,stroke-width:2px;

    %% Click Events for Decorators
    click D_Controller "https://github.com/naomis/router/blob/main/src/decorators/Controller.ts"
    click D_Get "https://github.com/naomis/router/blob/main/src/decorators/Get.ts"
    click D_Post "https://github.com/naomis/router/blob/main/src/decorators/Post.ts"
    click D_Delete "https://github.com/naomis/router/blob/main/src/decorators/Delete.ts"
    click D_Put "https://github.com/naomis/router/blob/main/src/decorators/Put.ts"

    %% Click Events for Core Infrastructure
    click C_MetadataStorage "https://github.com/naomis/router/blob/main/src/core/MetadataStorage.ts"
    click C_MethodFactory "https://github.com/naomis/router/blob/main/src/core/MethodDecoratorFactory.ts"
    click C_RouterRegistry "https://github.com/naomis/router/blob/main/src/core/RouterRegistry.ts"

    %% Click Event for Utilities
    click U_Utils "https://github.com/naomis/router/blob/main/src/utils/types.ts"

    %% Click Events for Examples
    click E_UserController "https://github.com/naomis/router/blob/main/examples/UserController.ts"
    click E_Server "https://github.com/naomis/router/blob/main/examples/server.ts"

    %% Click Events for Tests
    click T_ApiController "https://github.com/naomis/router/blob/main/tests/api.controller.ts"
    click T_ApiTest "https://github.com/naomis/router/blob/main/tests/api.test.ts"
    click T_IndexTest "https://github.com/naomis/router/blob/main/tests/index.test.ts"
```
