# kiwicom/starpicker architecture

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

- Interactive diagram: https://gitdiagram.com/kiwicom/starpicker
- Repository: https://github.com/kiwicom/starpicker

## Overview

##### Main Components
- Configuration Module – Represented by config.py. This module reads environment variables (e.g., SLACK_WEBHOOK_URL, REDIS_URL, API keys, and other settings).
- Collectors Module – Found in collectors.py. This component is in charge of communicating with external feedback sources such as trustpilot.com, Facebook, and Twitter.
- Reviews/Processing Module – Provided by reviews.py. This module likely handles the processing and possible formatting of the collected feedback.
- Runner/Execution Module – The run.py file serves as the entry point, orchestrating the periodic checks and managing the workflow.
- External Services – Indicate integrations for:
- Slack via SLACK_WEBHOOK_URL,
- Redis via REDIS_URL,
- Trustpilot, Facebook, and Twitter APIs using their respective API keys and tokens.

##### Relationships and Interactions
- The configuration reading process from config.py,
- The feedback retrieval process via collectors.py (which branches into separate collectors for each supported source).
- Once data is fetched, the Reviews module (reviews.py) processes or formats the feedback.
- Finally, the processed results trigger an outbound communication to Slack.
- Also, indicate that Redis is used as a caching or state management layer, perhaps to store the last checked state or deduplicate repeated notifications.

##### Architectural Patterns and Design Principles
- The design follows a modular approach where different responsibilities are separated into their respective files – a clear separation of concerns.
- There is a loosely coupled interaction between the data collection, review processing, and posting modules.
- Emphasis on an event or periodic scheduler pattern (in run.py) that handles the timely invocation of the collectors.
- External API integrations are abstracted inside the collectors, ensuring that the core logic remains modular and extensible.

##### Important Technologies and Frameworks
- Python is the primary language.
- Environment variable management is used for configuration.
- Integration with external services: Slack, Redis, and several external APIs for collecting feedback.
- Dockerfile and setup.py indicate deployment and packaging strategies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Starpicker Application"
        direction TB
        run["Execution/Orchestration (run.py)"]:::module
        config["Configuration (config.py)"]:::module
        collectors["Data Collectors (collectors.py)"]:::module
        reviews["Review Processing (reviews.py)"]:::module
    end

    subgraph "External Services"
        direction TB
        slack["Slack Webhook"]:::external
        redis["Redis Service"]:::external
        trustpilot["Trustpilot API"]:::external
        facebook["Facebook API"]:::external
        twitter["Twitter API"]:::external
    end

    run -->|"reads"| config
    config -->|"provides_API_keys"| collectors
    run -->|"invokes"| collectors
    collectors -->|"fetches_review_data_from"| trustpilot
    collectors -->|"fetches_review_data_from"| facebook
    collectors -->|"fetches_review_data_from"| twitter
    collectors -->|"caches_state_in"| redis
    collectors -->|"sends_data"| reviews
    reviews -->|"posts_formatted_result_to"| slack

    classDef module fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px,stroke-dasharray: 5 5;

    click config "https://github.com/kiwicom/starpicker/blob/master/starpicker/config.py"
    click collectors "https://github.com/kiwicom/starpicker/blob/master/starpicker/collectors.py"
    click reviews "https://github.com/kiwicom/starpicker/blob/master/starpicker/reviews.py"
    click run "https://github.com/kiwicom/starpicker/blob/master/starpicker/run.py"
```
