# ostend972/test architecture

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

- Interactive diagram: https://gitdiagram.com/ostend972/test
- Repository: https://github.com/ostend972/test

## Overview

##### Project type and purpose
- CalmWeb is a full-stack desktop application built with Electron.
- It provides real-time web-filtering via a local proxy (127.0.0.1:8081), a React/Vite renderer for the dashboard UI, and Node.js modules for proxy logic, configuration, updates and system integration on Windows 10/11.

##### File structure
- Top-level Electron files:
- main.js (Electron Main process)
- preload.js (context-isolated API exposure)
- index.html + App.jsx/App.tsx (Electron Renderer entry point)
- backend/ folder:
- proxy-server.js (HTTP/HTTPS proxy logic)
- blocklist-manager.js, whitelist-manager.js (domain filtering)
- config-manager.js, logger.js, updater.js, system-integration.js (app config, logging, silent updates, Windows proxy integration)
- validators, utils, ipc-validator (security and path checks)
- components/, services/, stores/:
- React components (Dashboard, Lists, Settings, Emergency modules)
- services/api.js (IPC or HTTP client abstraction)
- stores/configStore (Zustand) for local state
- hooks/useWebSocket (real-time feed)
- Configuration & deployment:
- electron-builder.json, installer.nsh, install-cleanup-task.ps1
- package.json, tsconfig.json, vite.config.ts
- %APPDATA% JSON files for config, logs, blocklists
- Tests: backend/__tests__ covering security and command-injection.

##### Key insights from README
- Electron multi-process architecture with sandboxed renderer and secure preload scripts.
- Local proxy filtering layered by blocklists (StevenBlack, Hagezi, URLhaus, PhishTank) plus custom whitelist/blocklist.
- Silent auto-updater, persistent logs for audit, system integration for Windows proxy settings and auto-start.

##### Main components
a. Electron Main Process
- Launches proxy server
- Manages auto-updates and system integration
- Hosts IPC channels
b. Backend Proxy Layer
- Incoming HTTP/HTTPS requests → proxy-server.js
- Validators (path, IPC) → blocklist/whitelist managers
- config-manager & logger write to local JSON stores
c. Renderer (React/UI)
- Dashboard components, Settings, Emergency button
- Communicates via IPC or HTTP fetch (services/api)
- State management with Zustand and React Query
d. Preload Script
- Exposes a restricted API surface for IPC calls
e. External Services
- Blocklist providers (StevenBlack, URLhaus, etc.) fetched by updater
- Windows OS (proxy configuration, auto-start)
f. Persistent Storage
- JSON files in %APPDATA%\CalmWeb\ (config.json, logs-persistent.json, whitelist.json, custom_blocklist.json)

##### Relationships and interactions
- User interacts with Renderer → triggers IPC/HTTP → Electron Main/Backend
- Proxy intercepts all network traffic → applies validators → logs events → forwards or blocks
- Updater periodically fetches external blocklists → updates local stores
- System integration module configures Windows proxy settings on start/stop
- Logger and config-manager persist to disk for dashboard display and audit

##### Architectural patterns & design principles
- Multi-process separation (Main vs. Renderer) with context isolation
- Modular backend services (single responsibility for proxy, blocklist, logging, updates)
- Reactive UI with component-driven design and state stores
- Layered filtering (validate → blocklist/whitelist → proxy forwarding)
- Secure IPC validation and path checks to prevent injection

##### Essential elements
- UI to API calls
- Proxy data flow (incoming requests → validators → blocklist/whitelist → network)
- Updater fetch flow
- System integration calls to Windows proxy settings
- UI components
- Backend services
- Storage
- External networks

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Electron Main & Backend"
        direction TB
        Main["Electron Main Process\n(main.js)"]:::main
        Preload["Preload Script\n(preload.js)"]:::main
        IndexBackend["Module Loader\n(backend/index.js)"]:::main
        Proxy["Proxy Server\n(proxy-server.js)"]:::main
        ValPath["Path Validator\n(path-validator.js)"]:::main
        ValIPC["IPC Validator\n(ipc-validator.js)"]:::main
        BlockMgr["Blocklist Manager\n(blocklist-manager.js)"]:::main
        WhiteMgr["Whitelist Manager\n(whitelist-manager.js)"]:::main
        ConfigMgr["Config Manager\n(config-manager.js)"]:::main
        Logger["Logger\n(logger.js)"]:::main
        Updater["Updater\n(updater.js)"]:::main
        SysInt["System Integration\n(system-integration.js)"]:::main
        Utils["Utilities\n(utils.js)"]:::main
    end

    subgraph "Renderer / UI"
        direction TB
        HTML["index.html"]:::renderer
        Entry["Renderer Entry\n(index.tsx)"]:::renderer
        App["Root React Component\n(App.jsx)"]:::renderer
        Dash["Dashboard Components"]:::renderer
        Lists["Lists Components"]:::renderer
        Settings["Settings Components"]:::renderer
        Emergency["Emergency Button"]:::renderer
        UIPrims["UI Primitives"]:::renderer
        API["IPC/API Client\n(services/api.js)"]:::renderer
        WS["WebSocket Hook\n(useWebSocket.js)"]:::renderer
        Store["State Store\n(configStore.js)"]:::renderer
    end

    subgraph "External Services"
        direction TB
        BlockExt["Blocklist Providers"]:::external
        WindowsOS["Windows OS"]:::external
        Network["Internet"]:::external
    end

    subgraph "Persistence\n(%APPDATA%/CalmWeb)"
        direction TB
        ConfigDB[(config.json)]:::storage
        LogsDB[(logs-persistent.json)]:::storage
        WhiteDB[(whitelist.json)]:::storage
        BlockDB[(custom_blocklist.json)]:::storage
    end

    %% Relationships
    Main -->|"launches"| Proxy
    Main -->|"uses"| Updater
    Main -->|"uses"| SysInt
    Main -->|"uses"| ConfigMgr
    Main -->|"uses"| Logger
    Main -->|"loads"| IndexBackend

    Preload ---|"exposes API"| Main
    HTML --> App
    Entry --> App
    App --> Dash
    App --> Lists
    App --> Settings
    App --> Emergency
    App --> UIPrims
    App --> API
    App --> WS
    App --> Store

    API -->|"IPC/HTTP"| Preload
    Store -->|"state"| App

    Network -->|"requests"| Proxy
    Proxy --> ValPath
    Proxy --> ValIPC
    ValPath -->|"checks"| BlockMgr
    ValIPC -->|"checks"| WhiteMgr
    BlockMgr -->|"reads"| BlockDB
    WhiteMgr -->|"reads"| WhiteDB
    Proxy -->|"forwards/blocks"| Network

    ConfigMgr -->|"writes"| ConfigDB
    Logger -->|"writes"| LogsDB
    Updater -->|"fetches"| BlockExt
    Updater -->|"writes"| BlockDB
    SysInt -->|"configures"| WindowsOS

    WindowsOS -.->|"proxy settings"| SysInt

    %% Click Events
    click Main "https://github.com/ostend972/test/blob/master/main.js"
    click Preload "https://github.com/ostend972/test/blob/master/preload.js"
    click HTML "https://github.com/ostend972/test/blob/master/index.html"
    click Entry "https://github.com/ostend972/test/blob/master/index.tsx"
    click App "https://github.com/ostend972/test/blob/master/App.jsx"
    click Dash "https://github.com/ostend972/test/tree/master/components/Dashboard/"
    click Lists "https://github.com/ostend972/test/tree/master/components/Lists/"
    click Settings "https://github.com/ostend972/test/tree/master/components/Settings/"
    click Emergency "https://github.com/ostend972/test/blob/master/components/Emergency/EmergencyButton.jsx"
    click UIPrims "https://github.com/ostend972/test/tree/master/components/ui/"
    click API "https://github.com/ostend972/test/blob/master/services/api.js"
    click WS "https://github.com/ostend972/test/blob/master/hooks/useWebSocket.js"
    click Store "https://github.com/ostend972/test/blob/master/stores/configStore.js"
    click IndexBackend "https://github.com/ostend972/test/blob/master/backend/index.js"
    click Proxy "https://github.com/ostend972/test/blob/master/backend/proxy-server.js"
    click BlockMgr "https://github.com/ostend972/test/blob/master/backend/blocklist-manager.js"
    click WhiteMgr "https://github.com/ostend972/test/blob/master/backend/whitelist-manager.js"
    click ConfigMgr "https://github.com/ostend972/test/blob/master/backend/config-manager.js"
    click Logger "https://github.com/ostend972/test/blob/master/backend/logger.js"
    click Updater "https://github.com/ostend972/test/blob/master/backend/updater.js"
    click SysInt "https://github.com/ostend972/test/blob/master/backend/system-integration.js"
    click ValPath "https://github.com/ostend972/test/blob/master/backend/path-validator.js"
    click ValIPC "https://github.com/ostend972/test/blob/master/backend/ipc-validator.js"
    click Utils "https://github.com/ostend972/test/blob/master/backend/utils.js"

    %% Styles
    classDef main fill:#cce5ff,stroke:#000
    classDef renderer fill:#d4edda,stroke:#000
    classDef external fill:#e2e3e5,stroke:#000,stroke-dasharray:5 5
    classDef storage fill:#fff3cd,stroke:#000,stroke-dasharray:2 2
```
