# tontonjo/calmweb architecture

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

- Interactive diagram: https://gitdiagram.com/tontonjo/calmweb
- Repository: https://github.com/tontonjo/calmweb

## Overview

##### Project Type and Purpose
- Calm Web is a Windows-based, system-wide HTTP/HTTPS proxy and web-filter tool written in Python.
- Its goal is to protect non-technical users by blocking ads, scams, remote-control tools, and unwanted domains via configurable blocklists and whitelists.
- It installs as a local proxy service, configures firewall rules and scheduled tasks, and periodically updates filter lists from remote sources.

##### Core Components
a. Installer Component
- calmweb_installer.py (packaged as calmweb_proxy.exe)
- Actions: copy files to C:\Program Files\CalmWeb, set up Windows Firewall rule, create Windows Scheduled Task, launch proxy service
b. Proxy Service / Filter Engine
- Python service that intercepts all HTTP/HTTPS traffic on localhost
- Loads blocklists/whitelists from local “filters” folder and remote URLs
- Applies domain-based and port-based filtering logic
- Logs blocked/allowed requests
c. Configuration & Data Storage
- Local filter files: filters/blocklist.txt, whitelist.txt, usefull_domains.txt, remote_desktop.txt
- Custom cfg under %appdata%\calmweb\custom.cfg for user-added rules
- ressources/readme.txt (documentation)
d. Scheduler & Updater
- Windows Scheduled Task triggers on startup (and periodic intervals)
- Updater module fetches and merges remote blocklists (StevenBlack, EasyList, DNS blocklists, URLHaus, etc.)
e. OS Integration Layer
- Windows Firewall API (enforce proxy port blocking)
- Windows Task Scheduler API
- System proxy settings (Windows registry or winhttp proxy)
f. Client Applications
- Any user browser or network-enabled program
- All outbound traffic is routed to the local proxy on port (e.g., 8080)

##### Relationships and Data Flow
1) User launches calmweb_proxy.exe → Installer sets up environment
2) Installer starts Proxy Service → registers service with OS
3) OS routes all HTTP/HTTPS traffic from Client Apps to Proxy Service
4) Proxy Service reads Configuration & Data Storage → builds in-memory filter rules
5) For each HTTP(S) request:
- Check domain/IP against Whitelist → allow immediately
- Else check against Blocklists or non-standard ports → block or drop
- Log outcome
- Forward allowed requests to destination server
6) Scheduler invokes Updater → fetches remote lists → updates local filter files → triggers Proxy Service reload of rules

##### Architectural Patterns & Design Principles
- Modular separation: installer, proxy engine, updater, storage, OS integration
- Single Responsibility: each module does one job (installation, filtering, updating)
- Plugin-style filter lists: easily add/remove blocklists or custom rules
- Resilience: scheduled updates, automatic startup, firewall enforcement

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Applications"
        direction TB
        Clients["User Browsers / Apps"]:::client
    end

    %% OS Integration Layer
    subgraph "OS Integration" 
        direction TB
        Firewall["Windows Firewall API"]:::os
        ProxySettings["System Proxy Settings\n(Registry/WinHTTP)"]:::os
        TaskSched["Windows Task Scheduler API"]:::os
    end

    %% Service Layer
    subgraph "Services" 
        direction TB
        Installer["Installer\n(calmweb_installer.exe)"]:::service
        ProxySvc["Proxy Service\nlocalhost:8080"]:::service
        Updater["Updater Module"]:::service
    end

    %% Filter Engine & Storage
    subgraph "Filter Engine & Config Store"
        direction TB
        FilterEngine["Filter Engine"]:::service
        subgraph "Local Filters (filters/)"
            direction TB
            Blocklist["blocklist.txt"]:::data
            Whitelist["whitelist.txt"]:::data
            UsefulDomains["usefull_domains.txt"]:::data
            RemoteDesktop["remote_desktop.txt"]:::data
        end
        CustomCFG["custom.cfg\n(%appdata%\\calmweb)"]:::data
        Doc["ressources/readme.txt"]:::doc
        README["README.md"]:::doc
    end

    %% External Data Sources
    subgraph "External Sources"
        direction TB
        StevenBlack["StevenBlack Hosts"]:::external
        EasyList["EasyList"]:::external
        DNSBL["Various DNS Blocklists"]:::external
        URLHaus["URLHaus"]:::external
    end

    %% Internet
    Internet["Internet\n(Destination Servers)"]:::external

    %% Connections: Installation & Startup
    Clients -->|"HTTP(S) traffic"| ProxySettings
    ProxySettings -->|redirect via 8080| ProxySvc
    Installer -->|install & configure| Firewall
    Installer -->|install & configure| TaskSched
    Installer -->|set proxy settings| ProxySettings
    Installer -->|launch service| ProxySvc

    %% Proxy Service Flow
    ProxySvc -->|load rules| FilterEngine
    FilterEngine --> Blocklist
    FilterEngine --> Whitelist
    FilterEngine --> UsefulDomains
    FilterEngine --> RemoteDesktop
    FilterEngine --> CustomCFG
    ProxySvc -->|forward allowed| Internet
    ProxySvc -->|log actions| Doc

    %% Scheduler & Updater
    TaskSched -->|trigger on startup/interval| Updater
    Updater -->|fetch & merge| StevenBlack
    Updater --> EasyList
    Updater --> DNSBL
    Updater --> URLHaus
    Updater -->|update files| Blocklist
    Updater --> Whitelist
    Updater --> UsefulDomains
    Updater --> RemoteDesktop
    Updater -->|notify reload| ProxySvc

    %% Legend
    subgraph "Legend"
        direction TB
        S["Services"]:::service
        D["Data Stores"]:::data
        E["External Sources"]:::external
        O["OS Integration"]:::os
        C["Documentation"]:::doc
    end

    %% Click Events
    click Installer "https://github.com/tontonjo/calmweb/blob/main/program/calmweb_installer.py"
    click Blocklist "https://github.com/tontonjo/calmweb/blob/main/filters/blocklist.txt"
    click Whitelist "https://github.com/tontonjo/calmweb/blob/main/filters/whitelist.txt"
    click UsefulDomains "https://github.com/tontonjo/calmweb/blob/main/filters/usefull_domains.txt"
    click RemoteDesktop "https://github.com/tontonjo/calmweb/blob/main/filters/remote_desktop.txt"
    click Doc "https://github.com/tontonjo/calmweb/blob/main/ressources/readme.txt"
    click README "https://github.com/tontonjo/calmweb/blob/main/README.md"

    %% Styles
    classDef service fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef data fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef os fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef client fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px;
    classDef doc fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-width:1px;
```
