# janik6n/typescript-starter architecture

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

- Interactive diagram: https://gitdiagram.com/janik6n/typescript-starter
- Repository: https://github.com/janik6n/typescript-starter

## Overview

##### Project Type and Purpose
- This is a backend-focused, “batteries-included” TypeScript starter boilerplate.
- It provides a development server, linting/formatting, testing (unit, integration, e2e), production bundling (esbuild), and optional Docker containerization.

##### Main Components
A. Source Code Layer
- src/index.ts (application entry point)
- src/models/config-model.ts (domain/model layer)
- src/utils/utils.ts (utility functions)
B. Dev Toolchain
- TSX (hot-reload development server, invoked by `npm run dev`)
- TypeScript compiler (type checking via `tsc --noEmit`)
- Esbuild bundler (production bundling via build.js)
- ESLint + Prettier (lint/format)
- Vitest (unit, integration, e2e test suites)
C. Build Output
- dist/ (compiled + bundled output)
D. Containerization
- Docker multi-stage build (builder image → production image)
E. CI/CD Pipeline
- GitHub Actions workflow (code-quality checks, tests)

##### Relationships and Data Flow
1. Developer writes code in VS Code (with ESLint & Vitest extensions).
2. `npm run lint` ↔ ESLint/Prettier → enforces code style.
3. `npm run test:*` ↔ Vitest → executes unit (.unit.test.ts), integration (.integration.test.ts), and e2e (.e2e.test.ts) against src/.
4. `npm run dev` ↔ TSX → runs index.ts in watch mode (hot reload).
5. `npm run build` →
- run `tsc --noEmit` (type checks)
- invoke build.js → Esbuild bundles src/ → outputs to dist/
6. Dist artifact can be:
- run locally via `npm run start` (node dist/index.mjs)
- packaged into a Docker image via `npm run build:container` → multi-stage Dockerfile → final production image.
7. CI (GitHub Actions) orchestrates lint, test, build pipelines on every push/pull request.

##### Architectural Patterns and Principles
- Modular code organization: clear separation between entrypoint, models, and utilities.
- Single responsibility: test files are grouped by test type.
- Dev/Prod parity: the same build pipeline runs locally and in CI.
- Container best practices: multi-stage build to minimize image size.

##### Detail Level
- Dockerfile stages (builder vs. runtime).
- That GitHub Actions listens on pushes/PRs and triggers lint, tests, build scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Editor
    Developer["Developer"]:::external
    Editor["VS Code Editor"]:::external
    Developer --> Editor

    %% Source Code Layer
    subgraph "Source Code Layer"
        direction TB
        Index["src/index.ts"]:::code
        ConfigModel["src/models/config-model.ts"]:::code
        Utils["src/utils/utils.ts"]:::code
    end
    Editor -->|"edits"| Index

    %% Dev Toolchain
    subgraph "Dev Toolchain"
        direction TB
        Linter["ESLint"]:::devtool
        Formatter["Prettier"]:::devtool
        TSX["TSX Dev Server"]:::devtool
        TSC["TypeScript Compiler"]:::devtool
        Esbuild["Esbuild Bundler"]:::devtool
        Vitest["Vitest Test Runner"]:::devtool
        UnitTests["Unit Tests"]:::devtool
        IntegrationTests["Integration Tests"]:::devtool
        E2ETests["E2E Tests"]:::devtool
    end

    %% Build Output
    subgraph "Build Output"
        direction TB
        Dist["dist/"]:::artifact
        NodeRun["Node Runtime"]:::artifact
    end

    %% Containerization
    subgraph "Containerization"
        direction TB
        DockerBuilder["Docker Builder Stage"]:::container
        ProdImage["Production Image"]:::container
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        direction TB
        GitHubActions["GitHub Actions (CI)"]:::ci
        Dependabot["Dependabot"]:::ci
    end

    %% Source Code to Dev Tools
    Index -->|"npm run lint"| Linter
    Index -->|"npm run lint"| Formatter
    Index -->|"npm run dev"| TSX
    Index -->|"npm run test:unit"| UnitTests
    Index -->|"npm run test:integration"| IntegrationTests
    Index -->|"npm run test:e2e"| E2ETests
    Index -->|"npm run build"| TSC

    %% Build Toolchain
    TSC -->|"tsc --noEmit"| Esbuild
    Esbuild -->|"build.js"| Dist
    Dist -->|"npm run start"| NodeRun
    Dist -->|"npm run build:container"| DockerBuilder
    DockerBuilder --> ProdImage

    %% CI/CD triggers
    GitHubActions --> Linter
    GitHubActions --> Vitest
    GitHubActions --> TSC
    GitHubActions --> Esbuild
    Dependabot --> GitHubActions

    %% Testing connections
    Vitest --> UnitTests
    Vitest --> IntegrationTests
    Vitest --> E2ETests

    %% Click Events
    click Index "https://github.com/janik6n/typescript-starter/blob/main/src/index.ts"
    click ConfigModel "https://github.com/janik6n/typescript-starter/blob/main/src/models/config-model.ts"
    click Utils "https://github.com/janik6n/typescript-starter/blob/main/src/utils/utils.ts"
    click UnitTests "https://github.com/janik6n/typescript-starter/blob/main/src/utils/utils.unit.test.ts"
    click IntegrationTests "https://github.com/janik6n/typescript-starter/blob/main/src/tests/sample.integration.test.ts"
    click E2ETests "https://github.com/janik6n/typescript-starter/blob/main/src/tests/sample.e2e.test.ts"
    click TSX "https://github.com/janik6n/typescript-starter/blob/main/package.json"
    click TSC "https://github.com/janik6n/typescript-starter/blob/main/tsconfig.json"
    click Esbuild "https://github.com/janik6n/typescript-starter/blob/main/build.js"
    click Linter "https://github.com/janik6n/typescript-starter/blob/main/eslint.config.mjs"
    click Formatter "https://github.com/janik6n/typescript-starter/blob/main/.prettierrc.json"
    click Vitest "https://github.com/janik6n/typescript-starter/blob/main/vitest.config.js"
    click Vitest "https://github.com/janik6n/typescript-starter/blob/main/vitest.workspace.js"
    click DockerBuilder "https://github.com/janik6n/typescript-starter/tree/main/Dockerfile"
    click ProdImage "https://github.com/janik6n/typescript-starter/blob/main/.dockerignore"
    click GitHubActions "https://github.com/janik6n/typescript-starter/blob/main/.github/workflows/code-quality-checks.yml"
    click Dependabot "https://github.com/janik6n/typescript-starter/blob/main/.github/dependabot.yml"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000
    classDef devtool fill:#90EE90,stroke:#000
    classDef artifact fill:#FFA500,stroke:#000
    classDef container fill:#D3D3D3,stroke:#000
    classDef ci fill:#DDA0DD,stroke:#000
    classDef external fill:#FFFFFF,stroke:#000,stroke-dasharray: 5 5
```
