# franksantillan/adt-take-home architecture

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

- Interactive diagram: https://gitdiagram.com/franksantillan/adt-take-home
- Repository: https://github.com/franksantillan/adt-take-home

## Overview

##### Project type and purpose
- This is not a traditional full-stack app but an **open-source test automation tool** built on Node.js, Cucumber.js, and TypeScript.
- Its purpose is to read Gherkin feature files, run BDD scenarios, collect results, and generate HTML reports—either locally or inside a Docker container, with CI integration via GitHub Actions.

##### File structure
- Top-level scripts & config:
- `cucumber.js`, `cucumber.json` (Cucumber config)
- `tsconfig.json`, `env.d.ts`, `types.d.ts` (TypeScript config/types)
- `Dockerfile`, `.dockerignore` (containerization)
- `.github/workflows/automated-tests.yml` (CI pipeline definition)
- Source code under `src/`:
- `features/` holds Gherkin `.feature` files and `step_definitions/` (.ts)
- `utils/` provides support modules: constants, test utils, reportUtils, plus a custom multiple-cucumber HTML reporter in `multiple-cucumber/reporter.ts`
- Scripts in `package.json` orchestrate:
- Test runs (`npx cucumber-js` with tags, format to JSON)
- Report generation (`multiple-cucumber-html-reporter`)
- Docker build & run to produce persistent test-results
- GitHub Actions badge indicates automated CI tests.

##### README for additional insights
- It clearly outlines the BDD scenarios (cucumber mathematics) and the end-to-end flow: from “Given/When/Then” definitions to HTML reports.
- It lists dependencies (Playwright, dayjs) that could extend functionality (e.g., browser-based testing or date handling).

a. Main components:
1. **Cucumber.js Engine**
2. **Feature Files** (`.feature`)
3. **Step Definitions** (`src/features/step_definitions/*.ts`)
4. **Utility Modules** (`src/utils/*` & multiple-cucumber reporter)
5. **Report Generator** (multiple-cucumber-html-reporter invoked via reporter.ts)
6. **Node.js/TypeScript Runtime** (ts-node)
7. **Docker Container**
8. **CI Pipeline** (GitHub Actions)
9. **Test Results Storage** (JSON files + HTML output)
b. Relationships & data flows:
- CI Pipeline → triggers Docker build & test run
- Docker Container ↔ Node.js runtime (with TypeScript via ts-node)
- Node.js runtime → Cucumber.js reads Feature Files → invokes Step Definitions
- Step Definitions call Utility Modules for shared logic, constants, date handling
- Cucumber.js outputs JSON test results → multiple-cucumber-html-reporter reads JSON → writes HTML report
- Reports mount back to host volume under `test-results/` for persistence
c. Architectural patterns / principles:
- **Modularization**: separate concerns between feature definitions, step logic, and utility/report modules
- **Pluggable reporting**: custom reporter module decoupled from test definitions
- **Containerization**: environment consistency via Dockerfile
- **CI-as-code**: GitHub workflow triggers reproducible test runs
d. Key technologies & libraries:
- Node.js, TypeScript, ts-node
- Cucumber.js (BDD runner)
- multiple-cucumber-html-reporter (HTML report generation)
- Playwright (optional browser tests), dayjs (date utils)
- Docker, GitHub Actions

##### Final advice
- Be as **detailed** as possible: include each folder or module that plays a role.
- **essential elements** without overcrowding: group similar utils under a “Utility Modules” cluster, group scripts under “npm scripts.”
- Keep labels consistent with file names (e.g., `multiple-cucumber/reporter.ts`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI Pipeline
    subgraph "CI Pipeline"
        CI["GitHub Actions CI Pipeline"]:::ci
    end

    %% Container Environment
    subgraph "Container Environment"
        Docker["Docker Container"]:::env
        Node["Node.js/TypeScript Runtime\n(ts-node)"]:::env
    end

    %% BDD Core
    subgraph "BDD Core"
        CucumberEngine["Cucumber.js Engine"]:::artifact
        FeatureFiles["Feature Files"]:::artifact
        StepDefs["Step Definitions"]:::artifact
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Constants["Constants"]:::artifact
        TestUtils["Test Utilities"]:::artifact
        ReportUtils["Report Utilities"]:::artifact
        ReporterCode["Custom Reporter\n(multiple-cucumber HTML reporter)"]:::artifact
    end

    %% Outputs
    subgraph "Outputs"
        JSONResults["JSON Test Results"]:::output
        HTMLReport["HTML Test Report"]:::output
    end

    %% Host Volume
    subgraph "Host Volume"
        Host["Host Volume\n(test-results/)"]:::env
    end

    %% Flows
    CI -->|"triggers build & test"| Docker
    Docker -->|"runs on"| Node
    Node -->|"executes"| CucumberEngine
    CucumberEngine -->|"reads"| FeatureFiles
    CucumberEngine -->|"invokes"| StepDefs
    StepDefs -->|"uses"| Constants
    StepDefs -->|"uses"| TestUtils
    StepDefs -->|"uses"| ReportUtils
    CucumberEngine -->|"outputs JSON"| JSONResults
    JSONResults -->|"consumed by"| ReporterCode
    ReporterCode -->|"generates"| HTMLReport
    Docker -->|"mounts volume"| Host
    JSONResults -->|"stored in"| Host
    HTMLReport -->|"stored in"| Host

    %% Click Events
    click CucumberEngine "https://github.com/franksantillan/adt-take-home/blob/main/cucumber.js"
    click CucumberEngine "https://github.com/franksantillan/adt-take-home/blob/main/cucumber.json"
    click FeatureFiles "https://github.com/franksantillan/adt-take-home/blob/main/src/features/cucumber.feature"
    click StepDefs "https://github.com/franksantillan/adt-take-home/blob/main/src/features/step_definitions/cucumber_steps.ts"
    click Constants "https://github.com/franksantillan/adt-take-home/blob/main/src/utils/constants.ts"
    click TestUtils "https://github.com/franksantillan/adt-take-home/blob/main/src/utils/testUtils.ts"
    click ReportUtils "https://github.com/franksantillan/adt-take-home/blob/main/src/utils/reportUtils.ts"
    click ReporterCode "https://github.com/franksantillan/adt-take-home/blob/main/src/utils/multiple-cucumber/reporter.ts"
    click Node "https://github.com/franksantillan/adt-take-home/blob/main/tsconfig.json"
    click Node "https://github.com/franksantillan/adt-take-home/blob/main/env.d.ts"
    click Node "https://github.com/franksantillan/adt-take-home/blob/main/types.d.ts"
    click Docker "https://github.com/franksantillan/adt-take-home/tree/main/Dockerfile"
    click Docker "https://github.com/franksantillan/adt-take-home/blob/main/.dockerignore"
    click CI "https://github.com/franksantillan/adt-take-home/blob/main/.github/workflows/automated-tests.yml"

    %% Styles
    classDef artifact fill:#9f6,stroke:#333,stroke-width:1px
    classDef env fill:#6cf,stroke:#333,stroke-width:1px
    classDef output fill:#f93,stroke:#333,stroke-width:1px
    classDef ci fill:#6cf,stroke:#333,stroke-width:1px
```
