# fernando-mashimo/github-users-db architecture

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

- Interactive diagram: https://gitdiagram.com/fernando-mashimo/github-users-db
- Repository: https://github.com/fernando-mashimo/github-users-db

## Overview

##### Project type and purpose
- This is a TypeScript-based CLI application (“github-users-db”) that fetches GitHub user data via the GitHub REST API, persists it in a PostgreSQL database (in Docker), and displays it in the terminal.
- It employs a Clean-Architecture/Hexagonal style: a thin CLI entrypoint, an application/use-case layer, a domain layer, and infrastructure adapters (database, GitHub API).

##### File structure
- Top-level scripts/config:
- docker-compose.yml (Postgres container)
- runMigrations.ts, runSeeds.ts, resetDb.ts (DB lifecycle)
- .env.example, infrastructure/config/database.ts (environment & DB config)
- src/cliApp.ts & src/cliApp_v2.ts: two implementations of the CLI entrypoint.
- src/application/useCases/: use-case interactors (fetchPersistUser, getUsersByFilters) with input/output DTOs and tests.
- src/domain/entities/user.ts: domain model for User.
- src/infrastructure/github/github.ts: GitHub API adapter.
- src/infrastructure/database/functions/*: CRUD functions for User persistence.
- src/infrastructure/database/migrations & seeds: SQL DDL/DML scripts.
- Tests and lint/jest configs.

##### README for additional insights
- Confirms technologies: Node.js 18+, TypeScript, Jest, ESLint, Docker/Postgres, optional Commander.js.

##### Detail without overthinking
- Every major folder as a component.
- Data flows (CLI → Use Case → Domain → Infra → External).
- Configuration scripts (migrations, seeds) as part of the Infrastructure block.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI1["CLI v1: src/cliApp.ts"]:::cli
        CLI2["CLI v2: src/cliApp_v2.ts"]:::cli
        CLI3["CLI Tests: src/cliApp.test.ts"]:::cli
    end

    %% Application Layer
    subgraph "Application Layer (Use Cases)"
        direction TB
        subgraph FetchPersistUser
            FP1["Index: fetchPersistUser/index.ts"]:::app
            FP2["Input DTO: fetchPersistUser/input.ts"]:::app
            FP3["Output DTO: fetchPersistUser/output.ts"]:::app
            FP4["Test: fetchPersistUserUseCase.test.ts"]:::app
        end
        subgraph GetUsersByFilters
            GF1["Index: getUsersByFilters/index.ts"]:::app
            GF2["Input DTO: getUsersByFilters/input.ts"]:::app
            GF3["Output DTO: getUsersByFilters/output.ts"]:::app
            GF4["Test: getUsersByFilters.test.ts"]:::app
        end
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DOMAIN["User Entity: src/domain/entities/user.ts"]:::domain
    end

    %% Infrastructure Adapters
    subgraph "Infrastructure Adapters"
        direction TB
        subgraph GitHubAdapter
            GH1["Adapter: src/infrastructure/github/github.ts"]:::infra
            GH2["Test: src/infrastructure/github/github.test.ts"]:::infra
        end
        subgraph DatabaseAdapter
            DB1["Create: src/infrastructure/database/functions/create.ts"]:::infra
            DB2["Read: src/infrastructure/database/functions/read.ts"]:::infra
            DB3["Update: src/infrastructure/database/functions/update.ts"]:::infra
        end
        subgraph Migrations
            MIG1["001_create_initial_tables.sql"]:::infra
            MIG2["002_add_columns_to_user_table.sql"]:::infra
            MIG3["Rollback: drop_tables.sql"]:::infra
        end
        subgraph Seeds
            SD1["001_seed_initial_data.sql"]:::infra
            SD2["002_update_added_columns_and_seed_new_user.sql"]:::infra
        end
        CFG["DB Config: src/infrastructure/config/database.ts"]:::infra
    end

    %% External Services & Scripts
    subgraph "External & Scripts"
        direction TB
        DC["Docker Compose: docker-compose.yml"]:::ext
        ENV["Env Example: .env.example"]:::ext
        RM["runMigrations.ts"]:::ext
        RS["runSeeds.ts"]:::ext
        RDB["resetDb.ts"]:::ext
    end

    %% External Systems
    GitHub["GitHub REST API"]:::external
    Postgres["PostgreSQL DB"]:::external

    %% Relationships
    CLI1 -->|"invoke command"| FP1
    CLI2 -->|"invoke command"| FP1
    FP1 -->|"uses Entity"| DOMAIN
    GF1 -->|"uses Entity"| DOMAIN
    FP1 -->|"HTTP"| GH1
    GH1 -->|"request/response"| GitHub
    FP1 -->|"SQL Insert/Update"| DB1
    FP1 -->|"SQL Read"| DB2
    GF1 -->|"SQL Read"| DB2
    GF1 -->|"returns DTO"| CLI1
    FP1 -->|"returns DTO"| CLI1
    CFG --> GH1
    CFG --> DB1
    CFG --> DB2
    CFG --> DB3
    DC --> Postgres
    RM --> Postgres
    RS --> Postgres
    RDB --> Postgres

    %% Click Events CLI
    click CLI1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/cliApp.ts"
    click CLI2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/cliApp_v2.ts"
    click CLI3 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/cliApp.test.ts"

    %% Click Events Application
    click FP1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/fetchPersistUser/index.ts"
    click FP2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/fetchPersistUser/input.ts"
    click FP3 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/fetchPersistUser/output.ts"
    click FP4 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/fetchPersistUser/fetchPersistUserUseCase.test.ts"
    click GF1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/getUsersByFilters/index.ts"
    click GF2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/getUsersByFilters/input.ts"
    click GF3 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/getUsersByFilters/output.ts"
    click GF4 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/application/useCases/getUsersByFilters/getUsersByFilters.test.ts"

    %% Click Events Domain
    click DOMAIN "https://github.com/fernando-mashimo/github-users-db/blob/main/src/domain/entities/user.ts"

    %% Click Events Infrastructure
    click GH1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/github/github.ts"
    click GH2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/github/github.test.ts"
    click DB1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/functions/create.ts"
    click DB2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/functions/read.ts"
    click DB3 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/functions/update.ts"
    click MIG1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/migrations/001_create_initial_tables.sql"
    click MIG2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/migrations/002_add_columns_to_user_table.sql"
    click MIG3 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/migrations/rollback/drop_tables.sql"
    click SD1 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/seeds/001_seed_initial_data.sql"
    click SD2 "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/database/seeds/002_update_added_columns_and_seed_new_user.sql"
    click CFG "https://github.com/fernando-mashimo/github-users-db/blob/main/src/infrastructure/config/database.ts"

    %% Click Events External & Scripts
    click DC "https://github.com/fernando-mashimo/github-users-db/blob/main/docker-compose.yml"
    click ENV "https://github.com/fernando-mashimo/github-users-db/blob/main/.env.example"
    click RM "https://github.com/fernando-mashimo/github-users-db/blob/main/src/runMigrations.ts"
    click RS "https://github.com/fernando-mashimo/github-users-db/blob/main/src/runSeeds.ts"
    click RDB "https://github.com/fernando-mashimo/github-users-db/blob/main/src/resetDb.ts"

    %% Styles
    classDef cli fill:#eee,stroke:#333,stroke-width:1px
    classDef app fill:#cfc,stroke:#333,stroke-width:1px
    classDef domain fill:#ccf,stroke:#333,stroke-width:1px
    classDef infra fill:#fcf,stroke:#333,stroke-width:1px
    classDef ext fill:#ddd,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
