How ostend972/test works
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