# liipeee/expense-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/liipeee/expense-tracker
- Repository: https://github.com/liipeee/expense-tracker

## Overview

##### Project type and purpose
- This is a backend REST API (“Expense Tracker”) built with Node.js/TypeScript, following Clean Architecture and Domain-Driven Design (DDD).
- It exposes CRUD endpoints for accounts, categories, contacts, addresses, and transactions, persists to PostgreSQL via Prisma, and uses JWT/Bcrypt for auth.

##### File structure
- **src/presentation**: HTTP controllers and DTOs (outermost “Interface” layer).
- **src/main**: Express adapters, routing, middleware, and factory functions (composition root).
- **src/data-layer**: Low-level use cases wired to repository ports and error handling (adapter layer).
- **src/domain**:
- Entities (core business objects)
- Use-case interfaces (application business rules)
- Repository interfaces (ports)
- Framework abstractions (JWT, Bcrypt)
- **src/infrastructure**:
- Prisma schema and migrations (database)
- Repository implementations (adapters/“driven” components)
- **test**: Unit tests for data-layer use cases.

##### Key insights from the README
- Emphasis on Clean Architecture layers: Domain → Application (Use Cases) → Infrastructure → Interface.
- Technologies: Node.js, TypeScript, Express, Prisma ORM, PostgreSQL, JWT, Bcrypt.

##### Main components
a. **Client / HTTP**
- HTTP clients (Postman, Frontend)
b. **API Layer (Express Server)**
- Express Adapter
- Routes & Middlewares
c. **Presentation**
- Controllers (handle request/response, map to DTOs)
d. **Application / Use Cases**
- Data-layer Use-Case classes (createAccount, getTransactions, etc.)
- Domain-use-case interfaces
e. **Domain Core**
- Entities (Account, Transaction, Contact, Category, Address)
- Value Objects & DTOs
- Repository Interfaces (IAcountRepository, ITransactionRepository, etc.)
- Framework Abstractions (JWT, Bcrypt)
f. **Infrastructure**
- Prisma Client (generated from schema.prisma)
- Repository Implementations (map domain entities ↔ database records)
g. **Database**
- PostgreSQL (migrations under prisma/migrations)
h. **External Services**
- JWT service, Bcrypt hashing

##### Relationships & data flow
- Client → Express Server
- Express Server → Presentation Controllers
- Controllers → Application Use Cases
- Use Cases → Domain Entities & Repository Interfaces
- Repository Interfaces → Infrastructure Repository Implementations
- Repository Implementations → Prisma Client → PostgreSQL
- Errors bubble up via custom error types (ApiError, NotFoundError, etc.)
- JWT/Bcrypt adapters called from Use Cases for auth/encryption

##### Architectural patterns & principles
- **Onion/Clean Architecture**: Core Domain at center, interfaces outwards.
- **Dependency Inversion**: Domain modules define repository interfaces; infrastructure implements them.
- **Factory Pattern**: Factories in src/main/factories wire controllers to use cases and adapters.
- **DTO & Mapper**: Presentation layer uses mappers to translate between domain and HTTP DTOs.
- **Error Handling**: Unified ApiError hierarchy in data-layer.

##### Detailed elements
- Component names (e.g., CreateTransactionController, CreateTransactionUseCase, TransactionRepository)
- Interfaces vs. implementations (label “ITransactionRepository” vs. “PrismaTransactionRepository”)
- Custom error flow (ApiError classes)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["HTTP Client (Postman/Frontend)"]:::external

    %% API Layer (Express)
    subgraph "API Layer" 
        direction TB
        ExpressIndex["Express Server\n(src/main/index.ts)"]:::framework
        ExpressAdapter["Express Adapter\n(src/main/adapters/express-adapter.ts)"]:::framework
        ExpressAdapterParam["Express Adapter w/ Params\n(src/main/adapters/express-adapter-with-param.ts)"]:::framework
        AppConfig["App Config\n(src/main/config/app.ts)"]:::framework
        RoutesConfig["Routes Config\n(src/main/config/routes.ts)"]:::framework
        MiddlewaresConfig["Middlewares\n(src/main/config/middlewares.ts)"]:::framework
        AccountsRoutes["Accounts Routes\n(src/main/routes/accounts-routes.ts)"]:::framework
        AddressRoutes["Address Routes\n(src/main/routes/address-routes.ts)"]:::framework
        CategoryRoutes["Category Routes\n(src/main/routes/category-routes.ts)"]:::framework
        ContactRoutes["Contact Routes\n(src/main/routes/contact-routes.ts)"]:::framework
        TransactionRoutes["Transaction Routes\n(src/main/routes/transaction-routes.ts)"]:::framework
    end

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        CreateAccountController["CreateAccountController"]:::presentation
        GetAllTransactionController["GetAllTransactionByAccountController"]:::presentation
        CreateTransactionController["CreateTransactionController"]:::presentation
    end

    %% Application Use Cases
    subgraph "Application Layer (Use Cases)" 
        direction TB
        CreateAccountUseCase["CreateAccountUseCase"]:::business
        GetAllTransactionUseCase["GetAllTransactionUseCase"]:::business
        CreateTransactionUseCase["CreateTransactionUseCase"]:::business
        ApiError["ApiError & Subclasses"]:::business
    end

    %% Domain Core
    subgraph "Domain Core" 
        direction TB
        AccountEntity["Account Entity"]:::business
        TransactionEntity["Transaction Entity"]:::business
        IAccountRepo["IAccountRepository"]:::business
        ITransactionRepo["ITransactionRepository"]:::business
        JWTAbstraction["JWT Abstraction"]:::external
        BcryptAbstraction["Bcrypt Abstraction"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure Layer" 
        direction TB
        PrismaSchema["Prisma Schema & Migrations"]:::framework
        PrismaAccountRepo["PrismaAccountRepository"]:::framework
        PrismaTransactionRepo["PrismaTransactionRepository"]:::framework
    end

    %% Database
    PostgreSQL[(PostgreSQL Database)]:::external

    %% Connections
    Client -->|"HTTP Request"| ExpressIndex
    ExpressIndex --> ExpressAdapter
    ExpressAdapter --> AppConfig
    AppConfig --> RoutesConfig
    RoutesConfig --> AccountsRoutes
    RoutesConfig --> AddressRoutes
    RoutesConfig --> CategoryRoutes
    RoutesConfig --> ContactRoutes
    RoutesConfig --> TransactionRoutes
    AccountsRoutes --> CreateAccountController
    AccountsRoutes --> GetAllTransactionController
    TransactionRoutes --> CreateTransactionController

    CreateAccountController -->|"execute(dto)"| CreateAccountUseCase
    GetAllTransactionController -->|"execute(params)"| GetAllTransactionUseCase
    CreateTransactionController -->|"execute(dto)"| CreateTransactionUseCase

    CreateAccountUseCase --> IAccountRepo
    GetAllTransactionUseCase --> IAccountRepo
    CreateTransactionUseCase --> ITransactionRepo
    CreateAccountUseCase -->|uses| BcryptAbstraction
    CreateAccountUseCase -->|uses| JWTAbstraction

    IAccountRepo --> PrismaAccountRepo
    ITransactionRepo --> PrismaTransactionRepo

    PrismaAccountRepo --> PrismaSchema
    PrismaTransactionRepo --> PrismaSchema
    PrismaSchema --> PostgreSQL

    %% Click Events - API Layer
    click ExpressIndex "https://github.com/liipeee/expense-tracker/blob/master/src/main/index.ts"
    click ExpressAdapter "https://github.com/liipeee/expense-tracker/blob/master/src/main/adapters/express-adapter.ts"
    click ExpressAdapterParam "https://github.com/liipeee/expense-tracker/blob/master/src/main/adapters/express-adapter-with-param.ts"
    click AppConfig "https://github.com/liipeee/expense-tracker/blob/master/src/main/config/app.ts"
    click RoutesConfig "https://github.com/liipeee/expense-tracker/blob/master/src/main/config/routes.ts"
    click MiddlewaresConfig "https://github.com/liipeee/expense-tracker/blob/master/src/main/config/middlewares.ts"
    click AccountsRoutes "https://github.com/liipeee/expense-tracker/blob/master/src/main/routes/accounts-routes.ts"
    click AddressRoutes "https://github.com/liipeee/expense-tracker/blob/master/src/main/routes/address-routes.ts"
    click CategoryRoutes "https://github.com/liipeee/expense-tracker/blob/master/src/main/routes/category-routes.ts"
    click ContactRoutes "https://github.com/liipeee/expense-tracker/blob/master/src/main/routes/contact-routes.ts"
    click TransactionRoutes "https://github.com/liipeee/expense-tracker/blob/master/src/main/routes/transaction-routes.ts"

    %% Click Events - Presentation
    click CreateAccountController "https://github.com/liipeee/expense-tracker/blob/master/src/presentation/controllers/account/create-account-controller.ts"
    click GetAllTransactionController "https://github.com/liipeee/expense-tracker/blob/master/src/presentation/controllers/account/get-all-transaction/get-all-transaction-by-account-controller.ts"
    click CreateTransactionController "https://github.com/liipeee/expense-tracker/blob/master/src/presentation/controllers/transaction/create-transaction-controller.ts"

    %% Click Events - Application
    click CreateAccountUseCase "https://github.com/liipeee/expense-tracker/blob/master/src/data-layer/usecase/account/create-account.usecase.ts"
    click GetAllTransactionUseCase "https://github.com/liipeee/expense-tracker/blob/master/src/data-layer/usecase/account/get-all-transaction.usecase.ts"
    click CreateTransactionUseCase "https://github.com/liipeee/expense-tracker/blob/master/src/data-layer/usecase/transaction/create-transaction.usecase.ts"
    click ApiError "https://github.com/liipeee/expense-tracker/blob/master/src/data-layer/errors/api-error.ts"

    %% Click Events - Domain
    click AccountEntity "https://github.com/liipeee/expense-tracker/blob/master/src/domain/entity/account.ts"
    click TransactionEntity "https://github.com/liipeee/expense-tracker/blob/master/src/domain/entity/transaction.ts"
    click IAccountRepo "https://github.com/liipeee/expense-tracker/blob/master/src/domain/repository/IAcountRepository.ts"
    click ITransactionRepo "https://github.com/liipeee/expense-tracker/blob/master/src/domain/repository/ITransactionRepository.ts"
    click JWTAbstraction "https://github.com/liipeee/expense-tracker/blob/master/src/domain/framework/jwt.ts"
    click BcryptAbstraction "https://github.com/liipeee/expense-tracker/blob/master/src/domain/framework/bcrypter.ts"

    %% Click Events - Infrastructure
    click PrismaSchema "https://github.com/liipeee/expense-tracker/blob/master/src/infrastructure/prisma/schema.prisma"
    click PrismaAccountRepo "https://github.com/liipeee/expense-tracker/blob/master/src/infrastructure/repository/account-repository.ts"
    click PrismaTransactionRepo "https://github.com/liipeee/expense-tracker/blob/master/src/infrastructure/repository/transaction-repository.ts"

    %% Styles
    classDef external fill:#DDDDDD,stroke:#888888,color:#333333;
    classDef framework fill:#CCE5FF,stroke:#3399FF,color:#03396C;
    classDef business fill:#D4EDDA,stroke:#28A745,color:#155724;
    classDef presentation fill:#FFF3CD,stroke:#FFEEBA,color:#856404;
```
