# clabnet/typescript-vitest-template architecture

> Architecture diagram of the GitHub repository clabnet/typescript-vitest-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clabnet/typescript-vitest-template
- Repository: https://github.com/clabnet/typescript-vitest-template

## Overview

##### Project Type and Purpose
- This is a boilerplate for building Node.js backend services/microservices in TypeScript.
- It provides fast development (esbuild + tsup watch), strict typing, linting (ESLint/Prettier), testing (Vitest), Docker production readiness, and optional Docker Compose orchestration.

##### File Structure
- Top-level:
- src/ (application source code; entry point src/index.ts)
- test/ (unit/integration tests via Vitest)
- build/ (tsc/tsup output: compiled .js + source maps)
- Dockerfile & compose.yaml (containerization & local orchestration)
- Config files: tsconfig.json, tsup.config.mjs, .env.example, .eslintrc, .prettierrc, etc.
- Patterns:
- Single-service (stateless) architecture
- Dev/build pipeline integrated (watchers, compilers, lint/test runners)
- Multi-stage Docker build for production image

##### Extract Key Architectural Insights from README
- Runtime: Node.js with source-map support
- Build tools: esbuild (dev), tsup (packaging), tsc (type checking)
- Linting: ESLint + Prettier plugin
- Testing: Vitest (CLI + UI)
- Env management: dotenv
- Docker: non-root user, multi-stage build; compose.yaml for local stacks

##### Main Components & Their Relationships
a. Developer Workstation
- Interacts with Git repo, runs pnpm scripts
- Launches `pnpm dev` → tsup + esbuild watchers → Node process (with debugger attached)
- Runs lint (`pnpm lint`), tests (`pnpm test`/`test:ui`), coverage (`test:coverage`)
b. Build Pipeline
- CI server (e.g., GitHub Actions) clones repo → installs via pnpm → runs lint/test → `pnpm build` → Docker build
c. Docker Multi-Stage Build
- Builder stage: uses Node base image + tsup to compile → outputs /build
- Final stage: minimal Node image + non-root user → copies /build + node_modules → ENTRYPOINT `node --enable-source-maps build/index.js`
d. Container Orchestration (Optional)
- compose.yaml may define this service alongside databases, caches, etc.
e. External Dependencies
- dotenv for env vars
- Typings folder for external module augmentations

##### Architectural Patterns & Design Principles
- Single Responsibility: separation of source (src), tests, build output
- Developer Feedback Loop: hot-reload watcher + type checking in parallel
- CI/CD: automated lint → test → build → containerize
- Twelve-factor inspiration: config via environment, strict builds, disposable containers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Layer
    subgraph "Developer Environment"
        direction TB
        Dev["Developer"]:::dev
        Git["Git Repository"]:::dev
        CI["CI Server"]:::dev
    end

    Dev -->|"push code"| Git
    Git -->|"CI Trigger"| CI

    %% Build & Dev Tools Layer
    subgraph "Development & Build Tools"
        direction TB
        tsupWatcher["tsup watcher\n(esbuild)"]:::tools
        tscWatcher["tsc watcher\n(type-check)"]:::tools
        lint["ESLint + Prettier"]:::tools
        test["Vitest Runner"]:::tools
    end

    Dev -->|"pnpm dev"| tsupWatcher
    Dev -->|"pnpm dev"| tscWatcher
    Dev -->|"pnpm lint"| lint
    Dev -->|"pnpm test"| test

    tsupWatcher -->|"streams code"| Service
    tscWatcher -->|"streams types"| Service

    %% Application Service Layer
    subgraph "Application Service"
        direction TB
        Service["Application Service\nsrc/index.ts"]:::app
        click Service "https://github.com/clabnet/typescript-vitest-template/blob/main/src/index.ts"
    end

    lint -->|"lint config"| Service
    test -->|"runs tests against"| Service

    %% Build Pipeline
    CI -->|"pnpm build"| buildOut

    subgraph "Build Output"
        direction TB
        buildOut["Build Output\nbuild/index.js,\nbuild/index.js.map"]:::build
        click buildOut "https://github.com/clabnet/typescript-vitest-template/blob/main/build/index.js"
    end

    %% Docker Layers
    subgraph "Docker Multi-Stage Build"
        direction TB
        DockerBuilder["Builder Stage\n(Dockerfile)"]:::infra
        click DockerBuilder "https://github.com/clabnet/typescript-vitest-template/tree/main/Dockerfile"
        DockerRuntime["Final Image\n(.dockerignore)"]:::infra
        click DockerRuntime "https://github.com/clabnet/typescript-vitest-template/blob/main/.dockerignore"
    end

    buildOut -->|"copy to builder"| DockerBuilder
    DockerBuilder -->|"produces image"| DockerRuntime

    subgraph "Container Orchestration"
        direction TB
        Container["Service Container\n(compose.yaml)"]:::infra
        click Container "https://github.com/clabnet/typescript-vitest-template/blob/main/compose.yaml"
    end

    DockerRuntime -->|"run service"| Container

    %% Configuration Files
    subgraph "Configuration"
        direction TB
        TSConfig["tsconfig.json"]:::config
        click TSConfig "https://github.com/clabnet/typescript-vitest-template/blob/main/tsconfig.json"
        TsupConfig["tsup.config.mjs"]:::config
        click TsupConfig "https://github.com/clabnet/typescript-vitest-template/blob/main/tsup.config.mjs"
        ESLint[".eslintrc.cjs"]:::config
        click ESLint "https://github.com/clabnet/typescript-vitest-template/blob/main/.eslintrc.cjs"
        Prettier[".prettierrc"]:::config
        click Prettier "https://github.com/clabnet/typescript-vitest-template/blob/main/.prettierrc"
        EnvExample[".env.example"]:::config
        click EnvExample "https://github.com/clabnet/typescript-vitest-template/blob/main/.env.example"
        Package["package.json"]:::config
        click Package "https://github.com/clabnet/typescript-vitest-template/blob/main/package.json"
        Typings["typings/"]:::config
        click Typings "https://github.com/clabnet/typescript-vitest-template/tree/main/typings/"
    end

    Package -->|"defines scripts/deps"| Dev
    TsupConfig -->|"configures"| tsupWatcher
    TSConfig -->|"configures"| tscWatcher
    ESLint -->|"configures"| lint
    Prettier -->|"configures"| lint
    EnvExample -->|"provides vars to"| Service
    Typings -->|"augmentations for"| Service

    %% Styles
    classDef dev fill:#D0E8FF,stroke:#6FA8DC
    classDef tools fill:#FFF2CC,stroke:#F1C232
    classDef app fill:#DFF2BF,stroke:#93C47D
    classDef build fill:#FCE5CD,stroke:#E69138
    classDef infra fill:#F4CCCC,stroke:#CC4125
    classDef config fill:#E1D5E7,stroke:#8E7CC3
```
