# tbrodbeck/kicktipp-bot-serverless architecture

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

- Interactive diagram: https://gitdiagram.com/tbrodbeck/kicktipp-bot-serverless
- Repository: https://github.com/tbrodbeck/kicktipp-bot-serverless

## Overview

##### Project type and purpose
- This is a lightweight, serverless “job”-style Python script (“Serverless Kicktipp Bot”) that uses Playwright to log into the Kicktipp website and submit tips automatically.
- It is not a long-running service. It is invoked on demand or on a schedule (e.g., Cron, AWS EventBridge, GCP Cloud Run triggers, Kubernetes CronJob).

##### File structure
- Top-level files: Dockerfile, docker-compose.yml, lambda_function.py (entry point), requirements.txt, setup.sh.
- CI/CD: .github/workflows/* defines build, test, publish, release pipelines.
- Kubernetes manifests under k8s/ (ConfigMap, Secrets, Deployment) hint at a CronJob or Deployment on K8s.
- E2E tests: e2e/*.spec.ts, tests-examples, tests/ indicate both Playwright tests (TypeScript) and Python unit tests.
- Lambda support: presence of lambda_function.py and packaging scripts implies AWS Lambda deployment option.
- Local dev: docker-compose-build.yaml and compose.yml for spinning up the container.

##### README for additional insights
- Describes environment variables for Kicktipp credentials, competition names, log level, notification webhooks (Zapier, NTFY).
- Mentions that it requires an external scheduler; can be deployed in Kubernetes or Cloud Run.

##### Main components
a. Scheduler component
- Cron job (on-premise) or AWS EventBridge / GCP Cloud Run trigger or Kubernetes CronJob.
b. Compute component (stateless job)
- AWS Lambda function OR Docker container running on Kubernetes or Cloud Run.
- Entry point: lambda_function.py.
- Runtime: Python + Playwright library.
c. Configuration component
- .env file or Kubernetes ConfigMap & Secrets storing KICKTIPP_EMAIL, PASSWORD, competition names, webhook URLs.
d. External systems
- Kicktipp website (target of browser automation).
- Zapier Webhook endpoint and/or NTFY server (notification receivers).
e. CI/CD pipeline
- GitHub Actions workflows: build image, run tests (unit and Playwright), publish Docker image, release.
f. Developer/local environment
- Docker Compose for building/running locally.
- Playwright local tests under e2e/.

##### Relationships and interactions
1. Scheduler → Compute:
- The scheduler triggers the container or Lambda function invocation.
2. Compute → Kicktipp Website:
- The Python/Playwright script opens a headless browser, logs in, reads game data, and submits tips.
3. Compute → Notification Service:
- After tipping, script optionally sends HTTP POST to Zapier or NTFY webhook.
4. Compute → Logs & Metrics:
- Emits logs (stdout, CloudWatch, or external logging).
5. CI/CD → Container Registry / Deployment:
- On push or release tag, GitHub Actions builds Docker image, runs tests, pushes to registry, and updates k8s deployment or Lambda function.

##### Architectural patterns and design principles
- Stateless, ephemeral compute: no persistent state; runs, finishes, and terminates.
- Infrastructure as code: Dockerfile, docker-compose, Kubernetes manifests, GitHub workflows.
- External scheduler pattern: decouples job scheduling from the application logic.
- Config-as-data: environment variables and secrets injected at runtime.
- CI/CD pipeline ensures repeatable builds, tests, and deployments.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Scheduler
    Scheduler["Scheduler<br/>(Cron/EventBridge/K8s CronJob)"]:::compute
    Scheduler -->|"invoke job"| Compute

    %% Compute
    subgraph "Compute Environment"
        Compute["Python + Playwright<br/>(lambda_function.py)"]:::compute
        Compute -->|"Browser automation"| Kicktipp["Kicktipp Website"]:::external
        Compute -->|"POST notification"| Zapier["Zapier Webhook"]:::external
        Compute -->|"POST notification"| NTFY["NTFY Server"]:::external
        Compute -->|"logs output"| Logs["Logs & Metrics"]:::external
        Compute -->|"Env vars / Secrets"| ConfigStore
    end

    %% Configuration Store
    subgraph "Configuration"
        ConfigMap["K8s ConfigMap"]:::config
        Secrets["K8s Secrets"]:::config
        EnvFile["Local .env.example"]:::config
    end
    Compute --> ConfigMap
    Compute --> Secrets
    DevLocal --> EnvFile

    %% Local Development
    subgraph "Developer Local Environment"
        DevLocal["Local Dev (Docker Compose)"]:::dev
        DevLocal --> DockerCompose["docker-compose.yml"]:::dev
        DevLocal --> DockerBuildOverride["docker-compose-build.yaml"]:::dev
        DevLocal --> Setup["setup.sh"]:::dev
        DevLocal --> Compute
        DevLocal --> E2ETests["Playwright E2E Tests"]:::dev
        DevLocal --> DemoTests["Demo App Specs"]:::dev
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions"]:::cicd
        CI --> BuildTest["Build & Test"]:::cicd
        CI --> Tests["Unit & Integration Tests"]:::cicd
        CI --> PlaywrightCI["Playwright E2E Tests"]:::cicd
        CI --> Publish["Docker Image Publish"]:::cicd
        CI --> Release["Release Pipeline"]:::cicd
        Publish --> Registry["Docker Registry"]:::external
        Registry --> Deployment["Update K8s Deployment / Lambda"]:::compute
    end

    %% Click Events
    click Scheduler "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/k8s/deployment.yaml"
    click Compute "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/lambda_function.py"
    click ConfigMap "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/k8s/configmap.yaml"
    click Secrets "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/k8s/secrets.yaml"
    click EnvFile "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/.env.example"
    click DockerCompose "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/docker-compose.yml"
    click DockerBuildOverride "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/docker-compose-build.yaml"
    click Setup "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/setup.sh"
    click BuildTest "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/.github/workflows/main.yaml"
    click Tests "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/.github/workflows/tests.yaml"
    click PlaywrightCI "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/.github/workflows/playwright.yml"
    click Publish "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/.github/workflows/docker-publish.yml"
    click Release "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/.github/workflows/release.yaml"
    click E2ETests "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/e2e/example.spec.ts"
    click DemoTests "https://github.com/tbrodbeck/kicktipp-bot-serverless/blob/main/tests-examples/demo-todo-app.spec.ts"

    %% Styles
    classDef compute fill:#cce5ff,stroke:#004085;
    classDef external fill:#d4edda,stroke:#155724;
    classDef config fill:#e2e3e5,stroke:#6c757d;
    classDef cicd fill:#fff3cd,stroke:#856404;
    classDef dev fill:#d1ecf1,stroke:#0c5460;
```
