# cambusahq/core architecture

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

- Interactive diagram: https://gitdiagram.com/cambusahq/core
- Repository: https://github.com/cambusahq/core

## Overview

##### Major Components
- API Layer: This includes the "api" directory with subdirectories for controllers (handling HTTP requests), models (data definitions and blueprints for automatic CRUD generation), hooks (lifecycle hooks/extensions), middlewares (request processing extensions), and helpers (utility functions).
- Configuration: Represent the "config" directory which centralizes database, routes, middlewares, security, logger, server, and swagger settings.
- Core Library/Framework: Include elements from the "src" directory under "src/lib" which holds core functionalities such as the cambusa global object, datastore management (EntitySubscriber, primaryKeyGenerator, etc.), routing logic (blueprints, validation, websocketHandler), and loader utilities for helpers, hooks, and middlewares.
- Deployment & Environment: Show Docker-related files (Dockerfile, docker-compose.yml) along with environment and linting configurations (e.g., .editorconfig, .prettierrc) which support deployment and development.

##### Out Relationships and Data Flow
- Global Application Instance ("cambusa" object): This acts as a central hub, providing access to configuration (cambusa.config), the logger (cambusa.log), the database (cambusa.db), models (cambusa.models), and helpers (cambusa.helpers).
- Routing: Show how custom routes defined in "config/routes.js" as well as auto-generated CRUD routes (blueprints) from models are passed to controllers found under "api/controllers".
- Business Logic and Middleware Chain: Indicate that incoming requests travel through a middleware pipeline (configured via "config/middlewares.js" and implemented in "api/middlewares") before reaching controllers that may use models and helpers.
- Persistence: Represent the database connection configured in "config/database.js" and the ORM integration (TypeORM) as part of the datastore logic in the "src/lib/datastore" directory.
- WebSocket and Real-Time Support: Include the separate pathway managed by the websocketHandler (under "src/lib/router/websocketHandler.js") for real-time connections.

##### Architectural Patterns and Design Principles
- MVC/Blueprint Pattern: Emphasize the resemblance to Sails.js. Models, controllers, and blueprints are used to generate standard CRUD operations automatically.
- Modular and Extensible Design: The separation of concerns with clearly defined directories for controllers, models, middleware, hooks, and helpers shows an extensible design where components can be individually maintained or replaced.
- Global Service Locator: The "cambusa" global object plays a central role for dependency access (configuration, logging, ORM, model management, etc.).
- Configurability: The extensive "config" directory facilitates environment-specific or centralized settings (security, routes, logger, etc.).

##### Relevant Technologies, Frameworks, and Libraries
- Bun as the runtime and bundler.
- Elysia (used internally in some components for middleware/plugins, e.g., in cors.js).
- TypeORM for database operations.
- Pino for logging.
- Docker for containerization.
- WebSocket integration for real-time communication.
- ESLint, Prettier, and other tooling for coding standards.

##### Essential Elements
- Component labels (e.g., “API Controllers”, “Middlewares”, “Database Models”, “Core Routers”).
- A section for deployment elements (Docker, environment configuration).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client and App Entry
    External["External Client (Browser/API)"]:::external
    AppEntry["App Entry (app.js)"]:::core
    External -->|"sends request"| AppEntry

    %% API Layer Subgraph
    subgraph "API Layer"
        APIMW["API Middlewares"]:::api
        APICT["API Controllers"]:::api
        APIMD["Models & Blueprints"]:::api
        APIHK["API Hooks"]:::api
        APIHP["API Helpers"]:::api
        APIMW -->|"to"| APICT
        APICT -->|"invokes"| APIMD
        APIMW -->|"triggers"| APIHK
        APICT -->|"utilizes"| APIHP
    end

    %% Core Library/Framework Subgraph
    subgraph "Core Library/Framework"
        GlobalObj["Global Object (cambusa)"]:::core
        DataStore["Data Store Management"]:::core
        Routing["Routing Logic (incl.WebSocketHandler)"]:::core
        Loader["Loader Utilities"]:::core
        Logger["Logger"]:::core
        GlobalObj -->|"manages"| DataStore
        GlobalObj -->|"controls"| Routing
        GlobalObj -->|"loads"| Loader
        GlobalObj -->|"logs"| Logger
    end

    %% Configuration Subgraph
    subgraph "Configuration"
        ConfigFiles["Configuration Files"]:::config
    end

    %% Deployment & Environment Subgraph
    subgraph "Deployment & Environment"
        DockerCompose["Docker & Compose"]:::deploy
        EnvConfig["Env & Linting Config"]:::deploy
    end

    %% Flow Connections
    AppEntry -->|"initializes"| APIMW
    AppEntry -->|"bootstraps"| GlobalObj
    GlobalObj -->|"accesses"| ConfigFiles
    APICT -- "uses" --> GlobalObj
    APICT -- "calls" --> DataStore
    Routing -->|"handles"| External

    %% Click Events for API Layer
    click APICT "https://github.com/cambusahq/core/blob/main/api/controllers/root.js"
    click APIMD "https://github.com/cambusahq/core/blob/main/api/models/Product.js"
    click APIHK "https://github.com/cambusahq/core/blob/main/api/hooks/exampleHook.js"
    click APIMW "https://github.com/cambusahq/core/blob/main/api/middlewares/cors.js"
    click APIHP "https://github.com/cambusahq/core/blob/main/api/helpers/ping.js"

    %% Click Events for Configuration
    click ConfigFiles "https://github.com/cambusahq/core/tree/main/config"

    %% Click Events for Core Library/Framework
    click GlobalObj "https://github.com/cambusahq/core/blob/main/src/lib/cambusa.js"
    click DataStore "https://github.com/cambusahq/core/tree/main/src/lib/datastore"
    click Routing "https://github.com/cambusahq/core/blob/main/src/lib/router/websocketHandler.js"
    click Loader "https://github.com/cambusahq/core/blob/main/src/lib/helpersLoader.js"
    click Logger "https://github.com/cambusahq/core/blob/main/src/lib/logger.js"

    %% Click Events for Deployment & Environment
    click DockerCompose "https://github.com/cambusahq/core/tree/main/Dockerfile"
    click EnvConfig "https://github.com/cambusahq/core/blob/main/eslint.config.js"

    %% Styles
    classDef external fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef core fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef deploy fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
