# ixpantia/faucet architecture

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

- Interactive diagram: https://gitdiagram.com/ixpantia/faucet
- Repository: https://github.com/ixpantia/faucet

## Overview

##### Main Components
- CLI/Entry Point: Represented by src/main.rs and src/cli.rs, this component parses command-line arguments (such as choosing the deployment directory, specifying the type—Plumber/Shiny/Quarto—and setting options for host, port, workers, and load balancing strategy).
- Server Core: The main server process (found in src/server) handles incoming HTTP requests. Inside this, include subcomponents such as:
- The Router (src/server/router/) which detects the type of application based on the provided directory and dispatches requests.
- A logging module (src/server/logging.rs) that captures events and error messages.
- Possibly the “onion” module (src/server/onion.rs) if it plays a role in multi-layered routing.
- Client Module: This module (inside src/client) handles communication between the server and application replicas, including:
- Load balancing submodules (e.g., Round Robin, IP Hash found in src/client/load_balancing) which decide how to distribute requests.
- Worker management (e.g., src/client/worker.rs) and connection pooling (src/client/pool.rs).
- Websockets support (src/client/websockets.rs) for real-time or persistent connections.
- Telemetry Module: (Located in src/telemetry) captures HTTP events and integrates with an external PostgreSQL database to record metrics and usage statistics.
- External Database Integration: Although not part of the codebase, include an external PostgreSQL node that stores telemetry data (using the FAUCET_TELEMETRY_POSTGRES_STRING).
- Supporting Scripts and Configurations: Incorporate configuration files (Cargo.toml, Dockerfile, GitHub workflows, etc.) that indicate build, deployment, and CI/CD pipelines.

- Inside the Server Core, illustrate how the Router determines the type of deployed application and hands off requests to the Client Module for load balancing.

##### Architectural Patterns and Design Principles
- Modular Separation: Clearly delineate modules for CLI, server, client, routing, logging, and telemetry.
- Asynchronous & Concurrent Processing: Annotate that the server utilizes asynchronous processing (leveraging Rust’s async ecosystem) to handle concurrent requests.
- Load Balancing Strategies: Represent the two main load balancing mechanisms (Round Robin and IP Hash) as alternative branches within the Client Module.
- Scalability & Replication: Indicate the possibility to spawn multiple workers (replicas) and show data flows that reflect decision-making by the load balancer.
- External Integration: Emphasize that the telemetry module interacts with an external PostgreSQL database, making it easier to trace performance metrics.

##### Relevant Technologies and Frameworks
- Rust (the programming language) and Cargo (Rust’s build tool) for the core application.
- Docker (via the Dockerfile and container examples) to containerize deployments.
- Nginx/Reverse Proxy (as shown in the README for routing requests properly).
- PostgreSQL (for HTTP telemetry storage).
- R-based application frameworks (Plumber APIs, Shiny, and Quarto as referenced in the usage examples).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Component
    EC["Nginx/Reverse Proxy"]:::external

    %% CLI / Entry Point
    CLI["CLI/Entry Point"]:::cli

    %% Supporting Scripts & Configurations
    subgraph "Supporting Scripts & Configurations"
        CS1["Cargo.toml & Cargo.lock"]:::config
        CS2["Dockerfile"]:::config
        CS3["CI/CD Workflows"]:::config
        CS4["Docs"]:::config
        CS5["Examples"]:::config
    end

    %% Telemetry and External Database
    T["Telemetry Module"]:::telemetry
    P["PostgreSQL"]:::database

    %% Server Core Subgraph
    subgraph "Server Core"
        SC1["Main Server Process"]:::server
        SC2["Router"]:::router
        SC3["Logging Module"]:::logging
        SC4["Onion Module"]:::onion
    end

    %% Client Module Subgraph
    subgraph "Client Module"
        CM1["Core Client Module"]:::client
        LB1["Load Balancing (Round Robin)"]:::loadbal
        LB2["Load Balancing (IP Hash)"]:::loadbal
        LB3["IP Extractor"]:::loadbal
        WM["Worker Management"]:::worker
        CP["Connection Pooling"]:::client
        WS["Websockets Support"]:::client
        OTH["Other Client Components"]:::client
    end

    %% Data Flows and Relationships
    EC -->|"forwards"| CLI
    CLI -->|"starts"| SC1
    CLI -->|"configures"| CS1

    SC2 -->|"dispatches"| CM1

    CM1 -->|"uses"| LB1
    CM1 -->|"uses"| LB2
    LB1 -->|"routes"| WM
    LB2 -->|"routes"| WM
    LB3 -->|"supports"| LB2
    CM1 --> CP
    CM1 --> WS
    CM1 --> OTH

    SC3 -->|"sends_logs"| T
    CM1 -->|"telemetry"| T
    T -->|"records_metrics"| P

    %% Styling Classes
    classDef external fill:#FCEFBF,stroke:#333,stroke-width:2px
    classDef cli fill:#ccf2ff,stroke:#333,stroke-width:2px
    classDef server fill:#c2f0c2,stroke:#333,stroke-width:2px
    classDef router fill:#a6e7a6,stroke:#333,stroke-width:2px
    classDef logging fill:#ffe6cc,stroke:#333,stroke-width:2px
    classDef onion fill:#ffccff,stroke:#333,stroke-width:2px
    classDef client fill:#d9ccff,stroke:#333,stroke-width:2px
    classDef loadbal fill:#e6ccff,stroke:#333,stroke-width:2px
    classDef worker fill:#ffd9b3,stroke:#333,stroke-width:2px
    classDef telemetry fill:#ffcccc,stroke:#333,stroke-width:2px
    classDef database fill:#cce0ff,stroke:#333,stroke-width:2px
    classDef config fill:#e6e6fa,stroke:#333,stroke-width:2px

    %% Click Events for CLI/Entry Point
    click CLI "https://github.com/ixpantia/faucet/blob/main/src/main.rs"
    click CLI "https://github.com/ixpantia/faucet/blob/main/src/cli.rs"

    %% Click Events for Server Core
    click SC1 "https://github.com/ixpantia/faucet/blob/main/src/server/mod.rs"
    click SC1 "https://github.com/ixpantia/faucet/blob/main/src/server/service.rs"
    click SC2 "https://github.com/ixpantia/faucet/blob/main/src/server/router/mod.rs"
    click SC3 "https://github.com/ixpantia/faucet/blob/main/src/server/logging.rs"
    click SC4 "https://github.com/ixpantia/faucet/blob/main/src/server/onion.rs"

    %% Click Events for Client Module
    click CM1 "https://github.com/ixpantia/faucet/blob/main/src/client/mod.rs"
    click LB1 "https://github.com/ixpantia/faucet/blob/main/src/client/load_balancing/round_robin.rs"
    click LB2 "https://github.com/ixpantia/faucet/blob/main/src/client/load_balancing/ip_hash.rs"
    click LB3 "https://github.com/ixpantia/faucet/blob/main/src/client/load_balancing/ip_extractor.rs"
    click WM "https://github.com/ixpantia/faucet/blob/main/src/client/worker.rs"
    click CP "https://github.com/ixpantia/faucet/blob/main/src/client/pool.rs"
    click WS "https://github.com/ixpantia/faucet/blob/main/src/client/websockets.rs"
    click OTH "https://github.com/ixpantia/faucet/blob/main/src/client/body.rs"

    %% Click Event for Telemetry Module
    click T "https://github.com/ixpantia/faucet/blob/main/src/telemetry/mod.rs"

    %% Click Events for Supporting Scripts & Configurations
    click CS1 "https://github.com/ixpantia/faucet/blob/main/Cargo.toml"
    click CS1 "https://github.com/ixpantia/faucet/blob/main/Cargo.lock"
    click CS2 "https://github.com/ixpantia/faucet/tree/main/Dockerfile"
    click CS3 "https://github.com/ixpantia/faucet/tree/main/.github/workflows/"
    click CS4 "https://github.com/ixpantia/faucet/tree/main/docs/"
    click CS5 "https://github.com/ixpantia/faucet/tree/main/examples/"
```
