# heavyrisem/hostrix architecture

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

- Interactive diagram: https://gitdiagram.com/heavyrisem/hostrix
- Repository: https://github.com/heavyrisem/hostrix

## Overview

##### Project type and purpose
- Hostrix is a desktop application built with Electron (main + preload) and a React/TypeScript/Vite renderer.
- Its core purpose is to provide host‐file and ping utilities via a modern UI that communicates with OS resources through Electron IPC.

##### File structure
● Top‐level “electron” folder
- main.ts – Electron main process entry point
- preload.js – Exposes a typed `window.ipc` bridge to renderer
- modules/… – A set of IPC modules (hosts, ping) each exporting invoke‐able methods
- libs/… – Lower‐level host‐file reader/writer utilities used by modules
● Top‐level “src” folder (the renderer)
- app/… – React entrypoint, global providers (React Query client, routing)
- features/… – Feature slices (hosts, home) with API wrappers, query keys, hooks
- entities/… – Reusable data access/query logic (e.g., sections)
- pages/… / routes/… / widgets/… – UI components, pages, sidebars, route definitions
- shared/… – Utility functions, type definitions for IPC
● Configuration
- pnpm-workspace.yaml, tsconfig.json, vite.config.ts – Monorepo, TS, and bundler config

##### README for additional insights
- Electron modules must be registered in `electron/modules/index.ts`.
- Renderer uses React Query to call `window.ipc.invoke(…)` for each module method.
- Types flow from `electron/modules` into `src/vite-env.d.ts` and shared/types, ensuring compile‐time safety.

1. Renderer/UI Layer (React + Vite)
- React Tree (pages, widgets, features)
- React Query Client & Hooks
2. Preload Script
- Exposes `window.ipc.invoke` API surface
3. Main Process / IPC Router
- IPC registration (electron/modules/index.ts)
4. IPC Modules
- hosts module (reader, writer, constants, utils)
- ping module
5. Underlying Libraries / OS Access
- File System (hosts file read/write)
- Network (ICMP ping)
6. Data Store (if applicable) – in this case the local hosts file on disk

- User clicks UI → React component calls React Query hook → React Query issues `window.ipc.invoke("moduleName", params)`
- Preload.js receives invoke → forwards to main process IPC handler → dispatches to the appropriate module function
- Module function calls into libs (FS or network) → returns result back up
- Main process returns result via IPC → Preload → Promise resolves in React Query → UI updates

c. Architectural patterns and design principles
- Clear separation of concerns: UI vs. IPC vs. OS logic
- Monorepo workspace sharing types and code (shared/types)
- Module‐based IPC “microservices” that are auto‐registered
- React Query as an abstraction over IPC calls for caching, error handling, automatic refetch

d. Key technologies and frameworks
- Electron (main, preload, IPC)
- React + TypeScript + Vite
- React Query
- pnpm workspaces
- Node.js FS & network (ping) APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Renderer (React + Vite)"
        UI["React Tree\n(pages, widgets, routing)"]:::renderer
        Providers["Providers\n(React Query Client)"]:::renderer
        Query["React Query Client & Hooks"]:::renderer
    end

    subgraph "Preload"
        Preload["Preload Script\n(window.ipc)"]:::preload
    end

    subgraph "Main Process"
        IPC["IPC Router\n(module registration)"]:::main
        subgraph "IPC Modules"
            HostsMod["Hosts Module"]:::module
            PingMod["Ping Module"]:::module
        end
    end

    subgraph "OS Services & Libs"
        subgraph "Hosts File Libs"
            Reader["Hosts Reader"]:::os
            Writer["Hosts Writer"]:::os
            Utils["Hosts Utils"]:::os
            Constants["Hosts Constants"]:::os
        end
        FS["File System\n(hosts file)"]:::os
        Network["Network (ICMP ping)"]:::os
    end

    subgraph "Shared Types"
        Types["Shared Types"]:::shared
    end

    %% Data Flow
    UI -->|"user action"| Providers
    Providers -->|"uses hooks"| Query
    Query -->|"ipc.invoke"| Preload
    Preload -->|"ipc call"| IPC
    IPC -->|"dispatch"| HostsMod
    IPC -->|"dispatch"| PingMod
    HostsMod -->|"read/write"| Reader
    HostsMod -->|"read/write"| Writer
    HostsMod -->|"utils/constants"| Utils
    HostsMod -->|"utils/constants"| Constants
    Reader -->|"fs access"| FS
    Writer -->|"fs access"| FS
    PingMod -->|"icmp ping"| Network
    HostsMod -->|"result"| IPC
    PingMod -->|"result"| IPC
    IPC -->|"response"| Preload
    Preload -->|"resolve promise"| Query
    Query -->|"update UI"| UI
    Types -.->|types| Preload
    Types -.->|types| Query

    %% Click Events
    click UI "https://github.com/heavyrisem/hostrix/tree/main/src/pages/"
    click UI "https://github.com/heavyrisem/hostrix/blob/main/src/widgets/app-sidebar.ui.tsx"
    click Providers "https://github.com/heavyrisem/hostrix/tree/main/src/app/providers/"
    click Query "https://github.com/heavyrisem/hostrix/blob/main/src/shared/query-client.ts"
    click Preload "https://github.com/heavyrisem/hostrix/blob/main/electron/preload.js"
    click IPC "https://github.com/heavyrisem/hostrix/blob/main/electron/main.ts"
    click IPC "https://github.com/heavyrisem/hostrix/blob/main/electron/modules/index.ts"
    click HostsMod "https://github.com/heavyrisem/hostrix/blob/main/electron/modules/hosts/index.ts"
    click PingMod "https://github.com/heavyrisem/hostrix/blob/main/electron/modules/ping/index.ts"
    click Reader "https://github.com/heavyrisem/hostrix/blob/main/electron/libs/hosts/reader.ts"
    click Writer "https://github.com/heavyrisem/hostrix/blob/main/electron/libs/hosts/writer.ts"
    click Utils "https://github.com/heavyrisem/hostrix/blob/main/electron/libs/hosts/utils.ts"
    click Constants "https://github.com/heavyrisem/hostrix/blob/main/electron/libs/hosts/constants.ts"
    click Types "https://github.com/heavyrisem/hostrix/blob/main/shared/types/hosts.ts"
    click Types "https://github.com/heavyrisem/hostrix/blob/main/src/vite-env.d.ts"
    click UI "https://github.com/heavyrisem/hostrix/blob/main/src/routes/routeMaps.tsx"
    click UI "https://github.com/heavyrisem/hostrix/blob/main/src/routes/home/index.tsx"
    click UI "https://github.com/heavyrisem/hostrix/blob/main/src/routes/hosts/index.tsx"
    click HostsMod "https://github.com/heavyrisem/hostrix/blob/main/src/features/hosts/api.ts"
    click HostsMod "https://github.com/heavyrisem/hostrix/blob/main/src/features/hosts/key.ts"
    click Providers "https://github.com/heavyrisem/hostrix/blob/main/src/app/app.tsx"
    click Providers "https://github.com/heavyrisem/hostrix/blob/main/src/app/index.tsx"
    click PingMod "https://github.com/heavyrisem/hostrix/blob/main/src/features/home/api.ts"
    click PingMod "https://github.com/heavyrisem/hostrix/blob/main/src/features/home/key.ts"

    %% Styles
    classDef renderer fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef preload fill:#C8F7C5,stroke:#333,stroke-width:1px
    classDef main fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef module fill:#FFD59E,stroke:#333,stroke-width:1px
    classDef os fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef shared fill:#F5D0C5,stroke:#333,stroke-width:1px
```
