# tgrecojs/capricorn architecture

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

- Interactive diagram: https://gitdiagram.com/tgrecojs/capricorn
- Repository: https://github.com/tgrecojs/capricorn

## Overview

##### Project Overview
- This is a Node.js/TypeScript HTTP server that creates “capability URLs.” When a client creates such a URL, the server saves the destination and a JavaScript transform function. Later, when that capability URL is used, the server uses the transform function to process the incoming request and then forwards it to the intended destination.
- The project uses a PostgreSQL database (as seen in the README and supported by files in the src/db folder) to persist capability details.

##### Main Components
a. Client/Consumer:
– Represents any external client making HTTP requests (both for creating capabilities and using them).
b. HTTP Server:
– Central component of the system that handles incoming HTTP requests. This would include the functionality provided by files like src/server.ts, src/index.ts, and the controller (src/controller.ts/test.ts).
c. Capability Controller:
– A specific controller module that processes requests to create capability URLs and forwards the processed requests.
d. Transformation Engine:
– This part is implicit in how the project lets you specify a JavaScript function to transform requests. Clearly indicate this as a logical component that “executes” the transform function provided by the client.
e. Database Layer:
– Represented by the src/db folder, this layer includes configuration (config.ts), migrations (under migrations/), and models (under models/). The DB is responsible for storing capability details and managing schema versions.
f. External Destination:
– When the transformed request is forwarded, it goes out to an external URL (destinationUrl). Display this as a component that shows an external API/service.

##### Relationships/Interactions to Capture
- The Client sends a POST request to the HTTP Server (“/create-capability”). The server, via the Capability Controller, processes the request, transforms it, and returns a capability URL.
- When a request comes in using the capability URL, the HTTP Server again intercepts the request, applies the transformation using the Transformation Engine, and then forwards the processed request to the External Destination.
- The HTTP Server interacts with the Database Layer to store, update, or retrieve the capability and routing information. Show bidirectional communication with the DB.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Data transformation, database operations, and request routing are all handled in modular components.
- Clear layering: Clients interact with the HTTP Server; the server uses controllers and a transformation module; persistent data operations are abstracted to a DB layer.
- Use of migrations to manage incremental changes to the database schema.

##### Tools and Technologies to Highlight
- Node.js with TypeScript (indicated by tsconfig.json and .ts files).
- PostgreSQL as the database.
- Docker (Dockerfile & .dockerignore) hinting at containerized deployment.
- External services – any service that is the target of a forwarded request.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client/Consumer"]:::client

    %% HTTP Server and related components
    HTTPServer["HTTP Server"]:::service
    CapabilityController["Capability Controller"]:::controller
    TransformationEngine["Transformation Engine"]:::service
    ExternalDestination["External Destination"]:::external

    %% Database Layer Subgraph
    subgraph "Database Layer"
        DBLayer["PostgreSQL Database"]:::database
        DBConfig["DB Config"]:::database
        Migrations["Migrations"]:::database
        Models["Models"]:::database
    end

    %% Interactions for capability creation
    Client -->|"POST/create-capability"| HTTPServer
    HTTPServer -->|"delegateTo"| CapabilityController
    CapabilityController -->|"executes"| TransformationEngine
    TransformationEngine -->|"forwardsRequest"| ExternalDestination

    %% Interaction with Database
    HTTPServer <-->|"dbOperations"| DBLayer
    DBLayer -->|"contains"| DBConfig
    DBLayer -->|"contains"| Migrations
    DBLayer -->|"contains"| Models

    %% Additional flow for capability usage
    Client -->|"usesCapabilityURL"| HTTPServer

    %% Click Events for Components
    click HTTPServer "https://github.com/tgrecojs/capricorn/blob/main/src/server.ts"
    click HTTPServer "https://github.com/tgrecojs/capricorn/blob/main/src/index.ts"
    click CapabilityController "https://github.com/tgrecojs/capricorn/blob/main/src/controller.ts"
    click CapabilityController "https://github.com/tgrecojs/capricorn/blob/main/src/controller.test.ts"
    click DBLayer "https://github.com/tgrecojs/capricorn/tree/main/src/db"
    click DBConfig "https://github.com/tgrecojs/capricorn/blob/main/src/db/config.ts"
    click Migrations "https://github.com/tgrecojs/capricorn/tree/main/src/db/migrations"
    click Models "https://github.com/tgrecojs/capricorn/tree/main/src/db/models"

    %% Styles
    classDef client fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#bfb,stroke:#333,stroke-width:2px;
    classDef controller fill:#ffb,stroke:#333,stroke-width:2px;
    classDef database fill:#fbb,stroke:#333,stroke-width:2px;
    classDef external fill:#bdf,stroke:#333,stroke-width:2px;
```
