# jancharatan/strava-auto-kudos architecture

> Architecture diagram of the GitHub repository jancharatan/strava-auto-kudos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jancharatan/strava-auto-kudos
- Repository: https://github.com/jancharatan/strava-auto-kudos

## Overview

##### Project Type & Purpose
- This is a specialized automation bot built in Python, designed to automatically give kudos on Strava whenever an authorized account posts a new activity.
- The README makes it clear that this bot integrates with Strava’s webhook mechanism and uses an ngrok tunnel for development/testing. It also involves user authentication with Strava’s API.

##### File Structure
- Top-Level Files:
- .gitignore, .pylintrc, and .vscode are for source control and code quality.
- README.md and shell scripts (startup.sh) offer setup and usage instructions.
- requirements Folder:
- Contains production and development dependencies, indicating that pip (or similar) is used to manage packages.
- src Directory:
- Contains the core application logic:
- app.py: Likely the main entry point for the web server/listener handling incoming webhook events.
- comments.py: Possibly handles posting kudos (or generating comments) as reactions to activities.
- selenium_utils.py: Provides Selenium-based automation; this is important since the bot might use browser automation to give kudos.
- strava_controller.py: Likely encapsulates logic related to interfacing with the Strava API (authentication, webhook subscription, etc.).

##### Components & Interactions
a. Main Components:
- Web Server (from src/app.py): Listens for incoming HTTP requests from Strava’s webhook.
- Strava Controller (src/strava_controller.py): Manages API interactions, including webhook subscription and authorization configuration.
- Bot Automation Module (using selenium_utils.py and comments.py): Uses Selenium for automating the browser actions (like logging into Strava and giving kudos) and possibly handling comment logic.
- Configuration & Environment: Relies on environment variables for Strava credentials and tokens as mentioned in the README. Also, the startup.sh script shows an initial configuration step.
- External Tools & Services:
- Strava API: The source of webhook events and the endpoint which triggers kudos.
- ngrok: Facilitates tunneling to localhost for development and testing. It is used to expose the local web server so that Strava can make callback requests.

b. Relationships & Data Flow:
- Strava and Webhook Layer: When a user uploads an activity, Strava sends a webhook event to the bot’s endpoint (e.g., at /webhook).
- Web Server (app.py): Receives the webhook, parses the event, and hands control over to the strava_controller.
- Strava Controller: Interacts with external Strava API details (e.g., validating tokens, processing event data) and triggers the awarding of kudos.
- Selenium Automation Module: Uses browser automation to log in to the authorized Strava account and to programmatically give kudos, with any additional logic possibly found in comments.py.
- Startup: The startup.sh initializes the setup and environment, ensuring required parameters and configurations are acquired.

##### Architectural Patterns & Technologies
- The design is a simple webhook-driven server. Its modular structure splits responsibilities (receiving requests, controlling API interactions, and managing automation) into separate modules. This separation enhances maintainability.
- Use of Selenium is notable – this implies the design adopts browser automation as a solution for the lack of direct API support for awarding kudos.
- The integration with ngrok shows a common design choice for overcoming the challenges of local development with externally accessible webhooks.

##### Essential Architectural Elements
- The external Strava API invoking the webhook.
- The intermediary role of ngrok redirecting traffic.
- The internal flow starting from the webserver (app.py), passing control to the Strava controller, and then invoking the automation module.
- Configuration dependencies (environment variables/settings) that guide the operation.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Components
    STRAVA["Strava API"]:::external
    NGROK["ngrok Tunnel"]:::external

    %% Internal Components
    subgraph "Internal System"
        WS["Web Server (app.py)"]:::internal
        SC["Strava Controller (strava_controller.py)"]:::internal
        AM["Automation Module (selenium_utils.py + comments.py)"]:::internal
        CONFIG["Configuration & Environment (startup.sh)"]:::config
        DEP["Dependency Management (requirements/)"]:::dependency
    end

    %% Data Flow
    STRAVA -->|"WebhookPOST"| NGROK
    NGROK -->|"ForwardRequest"| WS
    WS -->|"HandleWebhook"| SC
    SC -->|"TriggerKudos"| AM

    %% Configuration Influence
    CONFIG -.->|"configures"| WS
    CONFIG -.->|"configures"| SC
    CONFIG -.->|"configures"| AM

    %% Dependency Management Influence
    DEP -.->|"manages"| CONFIG

    %% Click Events
    click WS "https://github.com/jancharatan/strava-auto-kudos/blob/main/src/app.py"
    click SC "https://github.com/jancharatan/strava-auto-kudos/blob/main/src/strava_controller.py"
    click AM "https://github.com/jancharatan/strava-auto-kudos/blob/main/src/selenium_utils.py"
    click AM "https://github.com/jancharatan/strava-auto-kudos/blob/main/src/comments.py"
    click CONFIG "https://github.com/jancharatan/strava-auto-kudos/blob/main/startup.sh"
    click DEP "https://github.com/jancharatan/strava-auto-kudos/tree/main/requirements/"

    %% Style Definitions
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef internal fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef config fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef dependency fill:#FFFF99,stroke:#000,stroke-width:2px;
```
