# asheswook/tranjs architecture

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

- Interactive diagram: https://gitdiagram.com/asheswook/tranjs
- Repository: https://github.com/asheswook/tranjs

## Overview

##### Project type and purpose
- TranJS is a TypeScript-native, monorepo-based framework (managed by Lerna) that provides declarative transaction management for Node.js, without relying on ORMs.
- It consists of a core library plus pluggable drivers (e.g., mysql2, pg) that implement database-specific context and management.

##### File structure
- Top-level folders:
- packages/core – the heart of the framework (decorators, transaction manager, context propagation)
- packages/mysql2 and packages/pg – driver packages that bind core functionality to specific DB clients
- docs – API and implementation guides
- examples – minimal service code showing usage with each driver
- Configuration files: lerna.json (monorepo), tsconfig.json (shared), individual tsconfig.json and package.json in each package
- Tests live under packages/core/test, verifying core behavior (decorators, manager, async local storage)

##### README for additional insights
- Purpose: enable @Transactional decorator, manage commit/rollback automatically
- Features: no external dependencies, uses TypeScript decorators, leverages AsyncLocalStorage for context propagation
- Usage: user service classes call ctx().execute(…) under a transactional boundary

##### Detail without overthinking
- Sub-component of core (decorator.ts, manager.ts, asyncLocal.ts, context.ts) if needed
- Driver modules separately to illustrate the pluggable architecture
- Path of transaction context from entry (decorator) through to commit/rollback

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Application Layer
    subgraph "User Service (Application)" 
        direction TB
        US_MY["MySQL2 Example\nexamples/mysql2/main.ts"]:::user
        US_PG["Postgres Example\nexamples/pg/main.ts"]:::user
    end

    %% Core Framework Layer
    subgraph "Core Framework (packages/core)" 
        direction TB
        API["Public API\nindex.ts"]:::core
        DEC["Decorator & Proxy\ndecorator.ts"]:::core
        MGR["Transaction Manager\nmanager.ts"]:::core
        ALS["AsyncLocalStorage\nasyncLocal.ts"]:::core
        CTX["Transaction Context\ncontext.ts"]:::core
        PROP["Propagation Utils\npropagation.ts"]:::core
    end

    %% MySQL2 Driver Layer
    subgraph "MySQL2 Driver (packages/mysql2)" 
        direction TB
        MY_CTX["Driver Context Impl\ncontext.ts"]:::driver
        MY_MGR["Driver Manager Impl\nmanager.ts"]:::driver
        MY_API["Driver Public API\nindex.ts"]:::driver
    end

    %% Postgres Driver Layer
    subgraph "Postgres Driver (packages/pg)" 
        direction TB
        PG_CTX["Driver Context Impl\ncontext.ts"]:::driver
        PG_MGR["Driver Manager Impl\nmanager.ts"]:::driver
        PG_API["Driver Public API\nindex.ts"]:::driver
    end

    %% External Databases
    subgraph "Databases" 
        direction TB
        DB_MY["MySQL Database"]:::db
        DB_PG["PostgreSQL Database"]:::db
    end

    %% Connections
    US_MY -->|"@Transactional call"| DEC
    US_PG -->|"@Transactional call"| DEC

    DEC -->|"startTransaction()"| MGR
    MGR -->|"storeContext()"| ALS
    ALS -->|"uses"| CTX
    ALS -->|"uses"| PROP

    US_MY -->|"ctx().execute()"| MY_CTX
    US_PG -->|"ctx().execute()"| PG_CTX

    MY_CTX -->|"delegate execute()"| MY_MGR
    PG_CTX -->|"delegate execute()"| PG_MGR

    MY_MGR -->|"SQL queries"| DB_MY
    PG_MGR -->|"SQL queries"| DB_PG

    MY_MGR -->|"on success commitTransaction()"| MGR
    PG_MGR -->|"on success commitTransaction()"| MGR

    MY_MGR -->|"on error rollbackTransaction()"| MGR
    PG_MGR -->|"on error rollbackTransaction()"| MGR

    %% Click Events
    click US_MY "https://github.com/asheswook/tranjs/blob/main/examples/mysql2/main.ts"
    click US_PG "https://github.com/asheswook/tranjs/blob/main/examples/pg/main.ts"
    click DEC "https://github.com/asheswook/tranjs/blob/main/packages/core/src/decorator.ts"
    click MGR "https://github.com/asheswook/tranjs/blob/main/packages/core/src/manager.ts"
    click ALS "https://github.com/asheswook/tranjs/blob/main/packages/core/src/asyncLocal.ts"
    click CTX "https://github.com/asheswook/tranjs/blob/main/packages/core/src/context.ts"
    click PROP "https://github.com/asheswook/tranjs/blob/main/packages/core/src/propagation.ts"
    click API "https://github.com/asheswook/tranjs/blob/main/packages/core/src/index.ts"
    click MY_CTX "https://github.com/asheswook/tranjs/blob/main/packages/mysql2/src/context.ts"
    click MY_MGR "https://github.com/asheswook/tranjs/blob/main/packages/mysql2/src/manager.ts"
    click MY_API "https://github.com/asheswook/tranjs/blob/main/packages/mysql2/src/index.ts"
    click PG_CTX "https://github.com/asheswook/tranjs/blob/main/packages/pg/src/context.ts"
    click PG_MGR "https://github.com/asheswook/tranjs/blob/main/packages/pg/src/manager.ts"
    click PG_API "https://github.com/asheswook/tranjs/blob/main/packages/pg/src/index.ts"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef driver fill:#E6FFEA,stroke:#22863A,stroke-width:1px;
    classDef user fill:#F0F0F0,stroke:#6A737D,stroke-width:1px;
    classDef db fill:#FFEFD5,stroke:#D2691E,stroke-width:1px;
```
