# axiac/maroco architecture

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

- Interactive diagram: https://gitdiagram.com/axiac/maroco
- Repository: https://github.com/axiac/maroco

## Overview

- Testing Entry Point: The exported $route() function (located in src/_route.ts and referenced in the README) is the primary entry point. It determines which controller action is handling a specified HTTP verb and URL.
- Jest Matchers (src/matchers): A whole suite of matcher functions such as toBeHandled, toReturnJSON, toUseQueryParameter, etc. These components encapsulate the testing logic and ensure that the response and request handling follow expected rules.
- Metadata System (src/metadata): Components like Action.ts, Controller.ts, Route.ts, and metadataArgs.ts collect and manage metadata regarding controllers and their actions. This information is essential for the $route() function to resolve requests.
- Utility Functions (src/util): Support functions (for example, getDecoratorForVerb and type-checking utilities) used internally by both the $route function and the matchers to validate and format input.
- Tests: The tests directory mirrors the main structure by having corresponding test files for matchers and utilities. This verifies the correctness and expected behavior of each component.

- The testing code (tests directory) calls the $route() function with a HTTP verb and route, which then uses the metadata (extracted from the Routing Controllers annotations) to resolve the target controller action.
- Once the route is resolved, the returned object (the “route” object) is evaluated by the various Jest matchers in order to assert the specifics of its implementation (e.g., response type, parameter usage, HTTP headers).
- Utility functions support both the $route resolution and the operation of matchers by enforcing type expectations and handling decorator-based metadata.

##### Architectural patterns and design choices
- Modular Architecture: Components are organized into distinct folders (matchers, metadata, util) which indicates clean separation of concerns.
- Dependency Injection via Metadata: The system leverages metadata (decorators) to automatically wire up the controller actions with the corresponding routes, a common pattern in MVC or decorator-based frameworks.
- Testing Companion Library: The overall design is focused on testing; it’s intentionally decoupled from production code, acting as a companion to the Routing Controllers package by providing semantic matchers.
- Clear demarcation between core functionality (resolving route actions) and testing assertions (Jest matchers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ExtJest["Extern: Jest"]:::external
    ExtRouting["Extern: RoutingControllers"]:::external

    %% Testing Layer
    subgraph "Testing Layer"
        Tests["Tests"]:::testLayer
    end

    %% Core Routing Resolution Layer
    subgraph "Core Routing Resolution"
        Route["$route Function"]:::core
        Metadata["Metadata System"]:::core
        Util["Utility Functions"]:::util
    end

    %% Matcher Layer
    subgraph "Matcher Layer"
        Matchers["Jest Matchers"]:::testLayer
    end

    %% Connections
    Tests -->|"calls"| Route
    Route -->|"resolves via"| Metadata
    Route -->|"supports with"| Util
    Route -->|"returns route object to"| Matchers
    Matchers -->|"validates using"| Util

    %% External Dependencies connections
    ExtJest -->|"runs"| Tests
    ExtJest -->|"integrates with"| Matchers
    ExtRouting -->|"annotates"| Metadata

    %% Click Events
    click Route "https://github.com/axiac/maroco/blob/master/src/_route.ts"
    click Matchers "https://github.com/axiac/maroco/tree/master/src/matchers"
    click Metadata "https://github.com/axiac/maroco/tree/master/src/metadata"
    click Util "https://github.com/axiac/maroco/tree/master/src/util"
    click Tests "https://github.com/axiac/maroco/tree/master/tests"

    %% Styles
    classDef core fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef testLayer fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef external fill:#f94144,stroke:#333,stroke-width:2px;
    classDef util fill:#577590,stroke:#333,stroke-width:2px;
```
