# freedium-cfd/web architecture

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

- Interactive diagram: https://gitdiagram.com/freedium-cfd/web
- Repository: https://github.com/freedium-cfd/web

## Overview

##### Main components
- Frontend – Primarily in “new-web” (with Svelte components) handling client-side rendering and interactions.
- Reverse Proxy – Caddy is configured (under the “caddy” folder) to route HTTP/S traffic.
- Database Layer – There is a PostgreSQL instance (as indicated in the README and configuration files in “docker-compose”), and a Dragonfly-based key value store (mentioned in the stack as “redis_service”). There is also a separate “database-lib” used for database operations.
- Proxy Layer – This includes HAProxy (found in “proxy-balancer”) for load balancing and two WGCF clusters (using “wgcf” and the Dante configuration) to serve as Cloudflare WARP proxies.
- Analytics – Plausible is included as a service along with its own databases (ClickHouse and a PostgreSQL instance for Plausible).

##### Relationships and interactions
- The Main Application depends on the Reverse Proxy. The Caddy container is used to expose the application externally (with ports such as 6752).
- The backend web service (Freedium’s API) communicates with the Database Layer for content, while also possibly interacting with Redis/Dragonfly for caching.
- There are data flows from the Proxy Layer (HAProxy and WGCF clusters) to the Main Application; these components ensure proper internet routing, load balancing, and secure access.
- The Analytics service (Plausible) is connected with its databases to record user interactions.
- Inter-service Docker networks (like freedium_net, caddy_net, plausible_net) are used to structure communication between containers.

##### Architectural patterns & design principles
- Dockerized Microservices Architecture: Each service (backend, frontend, database, proxies) runs in its own container and is orchestrated via Docker Compose. This decomposition provides clear separation of responsibilities.
- API Gateway/Reverse Proxy Pattern: Caddy acts as the entry point into the system.
- Modular Separation: You have distinct modules for API, frontend, analytics, and proxy layers.

##### Relevant technologies, frameworks, and libraries
- Python, FastAPI/Unicorn for the backend.
- Jinja2 templating and Tailwind CSS (and planned Svelte frontend rewrite) for the UI.
- PostgreSQL, Dragonfly (acting as Redis/Memcached compatible database).
- Caddy, HAProxy, WGCF (Cloudflare WARP) for networking and proxy management.
- Analytics with Plausible and ClickHouse.
- Docker and Docker Compose for container orchestration.

- Each major component is clearly labeled (e.g., “Freedium API”, “Frontend UI”, “Caddy Reverse Proxy”, “HAProxy Load Balancer”, “WGCF Cluster 1/2”, “PostgreSQL DB”, “Dragonfly/Redis”, “Plausible Analytics”).
– Main Application → Database Layer
– Caddy ←→ Main Application
– HAProxy ←→ WGCF clusters → Main Application
– Frontend → API endpoints
– Analytics service → Analytics databases
- External access points with port connections (e.g., external port 6752 for Caddy, 7080 for the API service, etc.)
- Labels for Docker networks to show how inter-container communication is structured.

- Within the “Main Application” cluster, include the Freedium API (from “freedium-library” and “web”), indicating internal modules (API endpoints, business logic, etc.).
- Beside it, the “Frontend” cluster could note the “new-web” UI, communicating with the backend.
- Finally, the “Analytics” block should include Plausible and its databases.
- A “Utility” section for any extra service (like autoheal) that maintains service health.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Application Cluster
    subgraph "Main Application"
        A1["Freedium Library (API)"]:::service
        A2["Web Server (Templates)"]:::service
    end

    %% Frontend Cluster
    subgraph "Frontend"
        FE["Frontend UI"]:::service
    end

    %% Reverse Proxy Cluster
    subgraph "Reverse Proxy"
        C["Caddy Reverse Proxy (port 6752)"]:::proxy
    end

    %% Database Layer Cluster
    subgraph "Database Layer"
        DB1["PostgreSQL DB"]:::db
        DB2["Dragonfly/Redis Cache"]:::db
    end

    %% Proxy Layer Cluster
    subgraph "Proxy Layer"
        HL["HAProxy Load Balancer"]:::proxy
        WG["WGCF Cluster"]:::proxy
    end

    %% Analytics Cluster
    subgraph "Analytics"
        PA["Plausible Analytics"]:::service
        ADB["Analytics DB (ClickHouse/PG)"]:::db
    end

    %% Utility Cluster
    subgraph "Utility"
        U["Utility Monitoring (Autoheal)"]:::service
    end

    %% Docker Networks Cluster
    subgraph "Networks"
        N1["freedium_net"]:::network
        N2["caddy_net"]:::network
        N3["plausible_net"]:::network
    end

    %% Connections between clusters
    %% Reverse Proxy routes external traffic to Main Application
    C -->|"routes"| A2
    A2 -->|"responds"| C

    %% Frontend calls the backend API
    FE -->|"calls"| A1

    %% Main Application interacts with Database Layer
    A1 -->|"queries"| DB1
    A1 -->|"caches"| DB2

    %% Proxy Layer: HAProxy balances requests via WGCF to Main Application
    HL -->|"balances"| WG
    WG -->|"proxies to"| A1

    %% Analytics service logs data to its database
    PA -->|"logs"| ADB

    %% Utility Monitoring observes core services
    U --> A1
    U --> A2
    U --> C

    %% Docker Network associations (dashed lines for network binding)
    A1 ---|"on"| N1
    A2 ---|"on"| N1
    C  ---|"on"| N2
    PA ---|"on"| N3

    %% Click Events
    click A1 "https://github.com/freedium-cfd/web/tree/main/freedium-library"
    click A2 "https://github.com/freedium-cfd/web/tree/main/web"
    click FE "https://github.com/freedium-cfd/web/tree/main/new-web"
    click C "https://github.com/freedium-cfd/web/tree/main/caddy"
    click DB1 "https://github.com/freedium-cfd/web/blob/main/docker-compose/docker-compose.db.yml"
    click DB2 "https://github.com/freedium-cfd/web/tree/main/database-lib"
    click HL "https://github.com/freedium-cfd/web/tree/main/proxy-balancer"
    click WG "https://github.com/freedium-cfd/web/tree/main/wgcf"
    click PA "https://github.com/freedium-cfd/web/tree/main/plausible"
    click U "https://github.com/freedium-cfd/web/blob/main/docker-compose/docker-compose.utility.yml"

    %% Styles
    classDef service fill:#A2D5AB,stroke:#333,stroke-width:2px;
    classDef proxy fill:#F7A072,stroke:#333,stroke-width:2px;
    classDef db fill:#CFCFCF,stroke:#333,stroke-width:2px;
    classDef network fill:#D3E0EA,stroke:#333,stroke-width:2px;
```
