# just-boris/squash-umfrage architecture

> Architecture diagram of the GitHub repository just-boris/squash-umfrage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/just-boris/squash-umfrage
- Repository: https://github.com/just-boris/squash-umfrage

## Overview

##### Project type and purpose
- This is a serverless “Squash poll bot” for Telegram, implemented as a set of AWS Lambda functions and deployed via AWS CDK.
- Its purpose is to receive incoming updates from Telegram (via webhooks), schedule or send poll messages, and respond back to Telegram users.

##### File structure
- Top level:
- `cdk.json`, `src/infrastructure/…` – AWS CDK app that defines your cloud resources.
- `src/lambda/…` – all Lambda function code, plus its own `package.json`.
- `.env.example` – local test configuration for the Telegram bot token.
- `local-test.js` – helper to invoke Lambdas locally.
- Inside `src/infrastructure`:
- `index.ts` – CDK entrypoint (`App`).
- `notification-stack.ts` – CDK Stack that provisions the API Gateway, Lambdas, IAM roles, SSM parameter(s), and any scheduled events.
- Inside `src/lambda`:
- `index.ts` – the main webhook handler.
- `messages.ts`, `duration.ts`, `ssm.ts`, `utils.ts` – helper modules for message formatting, scheduling logic, SSM parameter retrieval, and common utilities.
- `src/interfaces.ts` holds TypeScript interfaces shared across both infra and Lambdas.

##### README
- Confirms deployment process: local testing (`npm start`), environment variables, then `npm run deploy` (AWS credentials).

##### Detail level and coverage
- Every AWS resource you create in CDK: API Gateway, each Lambda, Parameter Store, any scheduling resource.
- Don’t worry about file-level minutiae—focus on logical components and how they interplay to deliver the poll‑bot functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        TelegramUsers["Telegram Users"]:::external
        TelegramBotAPI["Telegram Bot API"]:::external
    end

    TelegramUsers -->|sends message| TelegramBotAPI

    %% Deployment Pipeline
    subgraph "Development & Deployment"
        direction TB
        DevMachine["Local Dev Machine"]:::code
        EnvExample[".env.example"]:::code
        LocalTest["local-test.js"]:::code
        CDKConfig["cdk.json"]:::code
        RootPkg["package.json"]:::code
        DevMachine -->|uses| EnvExample
        DevMachine -->|invokes| LocalTest
        DevMachine -->|runs| CDKConfig
        DevMachine -->|runs| RootPkg
        DevMachine -->|deploys| CDKApp
        click EnvExample "https://github.com/just-boris/squash-umfrage/blob/main/.env.example"
        click LocalTest "https://github.com/just-boris/squash-umfrage/blob/main/local-test.js"
        click CDKConfig "https://github.com/just-boris/squash-umfrage/blob/main/cdk.json"
        click RootPkg "https://github.com/just-boris/squash-umfrage/blob/main/package.json"
    end

    CDKApp["AWS CDK App (Deployment Pipeline)"]:::code
    click CDKApp "https://github.com/just-boris/squash-umfrage/blob/main/src/infrastructure/index.ts"

    %% Infrastructure Stack
    CDKApp --> CDKStack["CDK Stack (API Gateway, Lambdas, IAM, SSM, Scheduled Events)"]:::code
    click CDKStack "https://github.com/just-boris/squash-umfrage/blob/main/src/infrastructure/notification-stack.ts"

    %% AWS Resources
    subgraph "AWS Infrastructure" 
        direction TB
        APIGW["API Gateway (Webhook)"]:::aws
        SSM["SSM Parameter Store"]:::aws
        Events["CloudWatch Events / EventBridge"]:::aws

        subgraph "Lambda Functions"
            direction TB
            WebhookLambda["Webhook Handler Lambda"]:::lambda
        end
    end

    %% Runtime Flow
    TelegramBotAPI -->|HTTP POST webhook| APIGW
    APIGW -->|invokes| WebhookLambda
    WebhookLambda -->|reads bot token| SSM
    WebhookLambda -->|schedules poll| Events
    Events -->|triggers| WebhookLambda
    WebhookLambda -->|sends poll| TelegramBotAPI

    %% Lambda Code Modules
    subgraph "Webhook Handler Lambda Code" 
        direction TB
        LambdaIndex["index.ts"]:::code
        DurationMod["duration.ts"]:::code
        MessagesMod["messages.ts"]:::code
        SSMMod["ssm.ts"]:::code
        UtilsMod["utils.ts"]:::code
        Interfaces["interfaces.ts"]:::code
        LambdaIndex --> DurationMod
        LambdaIndex --> MessagesMod
        LambdaIndex --> SSMMod
        LambdaIndex --> UtilsMod
        LambdaIndex --> Interfaces
        click LambdaIndex "https://github.com/just-boris/squash-umfrage/blob/main/src/lambda/index.ts"
        click DurationMod "https://github.com/just-boris/squash-umfrage/blob/main/src/lambda/duration.ts"
        click MessagesMod "https://github.com/just-boris/squash-umfrage/blob/main/src/lambda/messages.ts"
        click SSMMod "https://github.com/just-boris/squash-umfrage/blob/main/src/lambda/ssm.ts"
        click UtilsMod "https://github.com/just-boris/squash-umfrage/blob/main/src/lambda/utils.ts"
        click Interfaces "https://github.com/just-boris/squash-umfrage/blob/main/src/interfaces.ts"
    end

    %% Styling
    classDef external fill:#FFD580,stroke:#E69A00,color:#000;
    classDef aws fill:#ACE7EF,stroke:#2980B9,color:#000;
    classDef lambda fill:#F3E5AB,stroke:#C19A6B,color:#000;
    classDef code fill:#D3D3D3,stroke:#696969,color:#000;
    class DevMachine,EnvExample,LocalTest,CDKConfig,RootPkg code;
    class CDKApp,CDKStack code;
    class APIGW,SSM,Events aws;
    class WebhookLambda lambda;
    class TelegramUsers,TelegramBotAPI external
```
