# swiss-digital-assets-institute/ts-coding-challenge architecture

> Architecture diagram of the GitHub repository swiss-digital-assets-institute/ts-coding-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swiss-digital-assets-institute/ts-coding-challenge
- Repository: https://github.com/swiss-digital-assets-institute/ts-coding-challenge

## Overview

##### Project Type & Purpose
- This is an **open-source test automation tool** (a Cucumber-based coding challenge) that validates Hedera SDK functionality (consensus topics and token services).
- Features in the README confirm it’s a test harness: feature files under `features/`, step definitions in TypeScript, and utility code under `src/` that calls the Hedera SDK against Testnet.

##### File Structure
Top level:
- `.env.example` / `config.ts` – environment/configuration for Hedera accounts and keys
- `features/`
– `*.feature` files: BDD scenarios for consensus and tokens
– `step_definitions/`: TypeScript implementations, currently incomplete
- `src/`
– `config.ts`: holds test keys & network info
– `create-accounts.ts`: helper to spin up Hedera accounts
- `cucumber.js`, `package.json`, `tsconfig.json`: build and test orchestration

##### README for Insights
- Describes workflow: fork, clone, install, inspect tests, implement missing code, then run `pnpm test`.
- Emphasizes not editing `.feature` files, but filling in the corresponding `.ts` files to drive Hedera SDK calls.

##### Main Components
a. **Test Runner**: Cucumber CLI (launched via `pnpm test`)
b. **Feature Layer**: `.feature` files define scenarios (consensus.feature, tokens.feature)
c. **Step Definition Layer**: TypeScript under `features/step_definitions/` that map Gherkin steps to code
d. **Implementation/Utility Layer**: files in `src/`—`config.ts`, `create-accounts.ts`, plus any future helpers
e. **Hedera SDK**: the external library used to call Hedera network services
f. **Hedera Testnet**: external system (topic service, token service) responding to SDK calls
g. **Environment/Configuration**: `.env` values or `config.ts` supplying credentials & network config

##### Relationships & Data Flow
1. **Developer** runs `pnpm test` →
2. **Cucumber Runner** picks up feature files →
3. Executes **Step Definitions** →
4. Invokes **Utility Functions** in `src/` →
5. Calls **Hedera SDK** client methods →
6. Sends transactions/queries to the **Hedera Testnet** →
7. Responses flow back to SDK →
8. SDK returns results to step definitions →
9. Cucumber asserts outcomes against Gherkin expectations

##### Architectural Patterns & Design Principles
- **Layered Architecture**: clear separation between:
- Gherkin scenarios (declarative spec)
- Step definitions (glue code)
- Utility modules (SDK wrappers)
- **Dependency Injection** of config values (via `config.ts` / environment variables)
- **Behavior-Driven Development** (BDD) pattern: requirements as living documentation
- Extensibility: new `.feature` files + corresponding step definitions can be added without altering core utilities.

##### Essential Elements
- Component names (exact folder/file names if desired)
- Data flows with arrowheads

- How BDD scenarios drive the code
- How code invokes the Hedera SDK
- How the external Testnet responds
- Where configuration sits

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Dev["Developer"]:::actor
    Runner["Cucumber Runner"]:::impl

    %% BDD Layer
    subgraph "BDD Artifacts"
        direction TB
        Features["Feature Files"]:::bdd
        ConsensusFeature["consensus.feature"]:::bdd
        TokensFeature["tokens.feature"]:::bdd
        Features --> ConsensusFeature
        Features --> TokensFeature
        StepDefs["Step Definitions"]:::bdd
        ConsensusFeature --> StepDefs
        TokensFeature --> StepDefs
        StepCreateTopic["create-simple-topic.ts"]:::bdd
        StepTokenService["token-service.ts"]:::bdd
        StepDefs --> StepCreateTopic
        StepDefs --> StepTokenService
    end

    %% Implementation/Utility Layer
    subgraph "Implementation (src)" 
        direction TB
        ConfigSrc["config.ts"]:::impl
        CreateAccounts["create-accounts.ts"]:::impl
        ConfigSrc -.-> CreateAccounts
    end

    %% Configuration
    EnvConfig[".env.example"]:::impl
    PackageJson["package.json"]:::impl
    TSConfig["tsconfig.json"]:::impl

    %% External Integrations
    SDK["Hedera SDK"]:::external
    Testnet["Hedera Testnet"]:::external

    %% Flows
    Dev -->|runs pnpm test| Runner
    Runner -->|loads features| Features
    StepDefs -->|invoke utilities| CreateAccounts
    StepDefs -->|load config| ConfigSrc
    CreateAccounts -->|calls SDK| SDK
    ConfigSrc -.->|inject config| SDK
    SDK -->|send transaction/query| Testnet
    Testnet -->|response| SDK
    SDK -->|return result| StepDefs
    StepDefs -->|assert outcomes| Runner

    %% Click Events
    click Runner "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/cucumber.js"
    click EnvConfig "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/.env.example"
    click ConsensusFeature "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/features/consensus.feature"
    click TokensFeature "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/features/tokens.feature"
    click StepCreateTopic "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/features/step_definitions/create-simple-topic.ts"
    click StepTokenService "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/features/step_definitions/token-service.ts"
    click ConfigSrc "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/src/config.ts"
    click CreateAccounts "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/src/create-accounts.ts"
    click PackageJson "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/package.json"
    click TSConfig "https://github.com/swiss-digital-assets-institute/ts-coding-challenge/blob/main/tsconfig.json"

    %% Styles
    classDef bdd fill:#e0f7e9,stroke:#2d7f5e,color:#2d7f5e;
    classDef impl fill:#e8f0fb,stroke:#2563eb,color:#2563eb;
    classDef external fill:#fff4e5,stroke:#f97316,color:#b45309;
    classDef actor fill:#f0f0f0,stroke:#888888,color:#555555,stroke-dasharray: 2 2;
```
