# francyfox/bunsqstat architecture

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

- Interactive diagram: https://gitdiagram.com/francyfox/bunsqstat
- Repository: https://github.com/francyfox/bunsqstat

## Overview

##### Project Type & Purpose
- This is a full-stack, monorepo application (built with Turbo) for real-time analysis of Squid proxy logs.
- It consists of:
- A Bun-based backend (“server”) that parses logs, indexes them in Redis, and serves APIs + WebSocket streams.
- A Vue 3 frontend (“web”) that renders dashboards, tables, and charts via HTTP + WS.
- A Redis Stack instance (with RediSearch) for full-text search and analytics.
- Docker configs & CI/CD workflows for containerized deployment.

##### File Structure Insights
- Top level:
- apps/server – Bun + TypeScript API & WS services, organized by modules (parser, access-logs, metrics, settings, watcher, ws).
- apps/web – Vue 3 SPA built with Vite, Composition API, Naive UI, UnoCSS, web workers, stores, pages, and components.
- packages – shared code (i18n, native-builder).
- docker & docker-compose files – config for Squid, Redis, Caddy, log rotation, multi‐container orchestration.
- docs – deployment, metrics, search syntax guides.
- CI/CD: GitHub Actions workflows for Docker image build & release.

##### Key Architectural Patterns
- Monorepo with Turbo for workspace builds.
- Modular backend: single process with clear service boundaries (parsing, metrics, settings, WS).
- Event-driven pipeline: watcher → parser → metrics → Redis → WS → UI.
- Pub/Sub via Redis and WebSocket for real-time updates.
- Frontend stores & workers isolate data fetching & heavy computations.

##### Main Components & Interactions
- Squid Proxy
- Generates access_log files (rotated by Squid).
- Log Watcher (apps/server/modules/watcher)
- Monitors log file changes, emits new lines.
- Parser (apps/server/modules/parser)
- Parses each log line into structured events.
- Metrics & Access-Logs Services (apps/server/modules/access-logs & metrics)
- Aggregate stats, compute hit ratios, top users/domains, RPS, durations.
- Redis Stack
- Stores raw events in streams or hashes, builds full-text indices via RediSearch for fast queries.
- WS Service (apps/server/modules/ws) & Elysia HTTP Routes
- Broadcasts real-time updates; serves REST endpoints (e.g., /api/search, /api/settings).
- Vue 3 Web UI
- Connects via HTTP to fetch historical/search data.
- Maintains a WebSocket for live updates.
- Uses Composition API, stores, and web workers (access.worker.ts) to offload processing.
- Shared Packages
- i18n: localization utilities.
- native-builder: custom build scripts.
- DevOps/CICD
- Dockerfiles for frontend, backend.
- docker-compose for all-in-one or prod.
- GitHub Actions for image build & release.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        Squid["Squid Proxy<br/>access_logs"]:::external
        CI_CD["GitHub Actions (CI/CD)"]:::external
    end

    %% DevOps
    subgraph "DevOps"
        direction TB
        DockerCompose["Docker Compose"]:::devops
        DockerConfigs["Docker Configs"]:::devops
    end

    %% Monorepo Structure
    subgraph "Monorepo"
        direction TB
        Turbo["Turbo Monorepo"]:::devops

        %% Backend
        subgraph "apps/server"
            direction TB
            Entrypoint["Server Entry (index.ts)"]:::backend
            BuildConfig["Server Build & Config"]:::backend
            RedisClient["Redis Client & Config"]:::backend
            Watcher["Log Watcher"]:::backend
            Parser["Parser Service"]:::backend
            AccessLogsService["Access-Logs Service"]:::backend
            MetricsService["Access-Logs Metrics Service"]:::backend
            SettingsService["Settings Service"]:::backend
            StatsModule["Stats Module"]:::backend
            HTTPServer["Elysia HTTP API"]:::backend
            WSService["WebSocket Service"]:::backend
        end

        %% Data Store
        subgraph "Data Store"
            direction TB
            Redis["Redis Stack<br/>(RediSearch)"]:::datastore
        end

        %% Frontend
        subgraph "apps/web"
            direction TB
            WebUI["Vue 3 SPA"]:::frontend
            HTTPClient["HTTP Client Module"]:::frontend
            WSClient["WebSocket Composable"]:::frontend
            WebWorker["Web Worker"]:::frontend
            Stores["Frontend Stores"]:::frontend
            Pages["Frontend Pages"]:::frontend
            Components["Frontend Components"]:::frontend
        end

        %% Shared Packages
        subgraph "packages"
            direction TB
            i18n["i18n Package"]:::shared
            NativeBuilder["Native-Builder Package"]:::shared
        end
    end

    %% External to Backend Flow
    Squid -->|"access_log files"| Watcher
    CI_CD -->|"triggers builds"| Turbo

    %% Backend Pipeline
    Watcher -->|"new lines"| Parser
    Parser -->|"structured events"| AccessLogsService
    AccessLogsService -->|"aggregated stats"| MetricsService
    MetricsService -->|"index data"| Redis
    AccessLogsService -->|"raw events"| Redis
    SettingsService -->|"settings"| Redis
    StatsModule -->|"compute stats"| Redis

    %% Pub/Sub & APIs
    Redis -->|"pub/sub"| WSService
    HTTPClient -->|"HTTP /api/*"| HTTPServer
    WebUI -->|"HTTP"| HTTPServer
    WSClient -->|"WebSocket"| WSService
    WebUI -->|"WS subscribe"| WSService

    %% Frontend internal
    WebUI --> HTTPClient
    WebUI --> WSClient
    WebUI --> WebWorker
    WebUI --> Stores
    WebUI --> Pages
    WebUI --> Components

    %% DevOps Deployment
    DockerCompose -->|"deploy containers"| Squid
    DockerCompose -->|"deploy containers"| Redis
    DockerCompose -->|"deploy containers"| Entrypoint
    DockerCompose -->|"deploy containers"| WebUI
    DockerConfigs --> DockerCompose

    %% Shared Packages Usage
    Entrypoint --> i18n
    Entrypoint --> NativeBuilder
    WebUI --> i18n
    WebUI --> NativeBuilder

    %% Click Events
    click Watcher "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/watcher/index.ts"
    click Parser "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/parser/service.ts"
    click AccessLogsService "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/access-logs/service.ts"
    click MetricsService "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/access-logs/metrics/service.ts"
    click SettingsService "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/settings/service.ts"
    click StatsModule "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/stats/index.ts"
    click WSService "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/modules/ws/index.ts"
    click HTTPServer "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/routes.ts"
    click RedisClient "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/redis.ts"
    click Entrypoint "https://github.com/francyfox/bunsqstat/blob/master/apps/server/src/index.ts"
    click BuildConfig "https://github.com/francyfox/bunsqstat/blob/master/apps/server/build.ts"
    click WebUI "https://github.com/francyfox/bunsqstat/blob/master/apps/web/src/main.ts"
    click HTTPClient "https://github.com/francyfox/bunsqstat/blob/master/apps/web/src/api.ts"
    click WSClient "https://github.com/francyfox/bunsqstat/blob/master/apps/web/src/composables/ws-access.ts"
    click WebWorker "https://github.com/francyfox/bunsqstat/blob/master/apps/web/src/workers/access.worker.ts"
    click Stores "https://github.com/francyfox/bunsqstat/tree/master/apps/web/src/stores"
    click Pages "https://github.com/francyfox/bunsqstat/tree/master/apps/web/src/pages"
    click Components "https://github.com/francyfox/bunsqstat/tree/master/apps/web/src/components"
    click i18n "https://github.com/francyfox/bunsqstat/tree/master/packages/i18n"
    click NativeBuilder "https://github.com/francyfox/bunsqstat/tree/master/packages/native-builder"
    click DockerCompose "https://github.com/francyfox/bunsqstat/blob/master/docker-compose.yml"
    click DockerConfigs "https://github.com/francyfox/bunsqstat/tree/master/docker/"
    click CI_CD "https://github.com/francyfox/bunsqstat/blob/master/.github/workflows/docker-image.yml"
    click Turbo "https://github.com/francyfox/bunsqstat/blob/master/turbo.json"

    %% Styles
    classDef backend fill:#D6E8FF,stroke:#4D89F9,stroke-width:1px;
    classDef frontend fill:#E6F9E6,stroke:#34A853,stroke-width:1px;
    classDef datastore fill:#FFE6E6,stroke:#EA4335,stroke-width:1px;
    classDef external fill:#F5F5F5,stroke:#999999,stroke-width:1px,stroke-dasharray: 2 2;
    classDef devops fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2;
    classDef shared fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px;
```
