# foru17/neko-master architecture

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

- Interactive diagram: https://gitdiagram.com/foru17/neko-master
- Repository: https://github.com/foru17/neko-master

## Overview

##### Project Type and Purpose
- Neko Master is a full-stack, monorepo application for real-time network traffic monitoring, auditing, and visualization.
- It consists of two primary services:
- Collector (Node.js + Fastify + WebSocket)
- Web UI (Next.js + React + TypeScript)
- A shared package holds common types/utilities.

##### File Structure Analysis
- Top-level directories:
- apps/collector – back-end data collector service
- apps/web – front-end Next.js application
- packages/shared – cross-service utilities and type definitions
- Config and deployment artifacts:
- Dockerfile, docker-compose.yml, setup/start scripts
- .env examples and CI workflows
- Collector uses a modular MVC-style layout: controllers, services, repositories, schema.
- Web app follows Next.js’s app directory structure, with localized pages, shared UI components, hooks, lib, i18n, public assets.

##### Key Architecture Insights from README
- Ports: 3000 (Web UI), 3001 (Collector REST API), 3002 (Collector WebSocket)
- Frontend proxies `/api` to port 3001 and connects to `/_cm_ws` for real-time updates on 3002.
- Data persistence via SQLite (stats.db).
- Fallback to HTTP polling (~5s) if WS isn’t available.
- Deployment typically via Docker Compose with optional Nginx or Cloudflare Tunnel reverse proxy for unified domain and WS upgrade.

- Browser (User)
- Next.js Frontend (apps/web)
- Fastify Collector (apps/collector)
- SQLite Database (stats.db)
- External Network Gateways (e.g., OpenClash backends)
- Shared Library (packages/shared)
- Reverse Proxy (Nginx / Cloudflare Tunnel) – optional in production
1. Browser → HTTP GET `/` → Frontend
2. Frontend → HTTP REST → Collector API (port 3001)
3. Frontend → WebSocket Upgrade → Collector WS (port 3002)
4. Collector ↔ SQLite (read/write stats)
5. Collector → Poll/WebSocket request → External Gateways
6. Reverse Proxy routes `/` → 3000 and `/_cm_ws` → 3002
c. Architectural Patterns & Principles:
- Separation of concerns: UI vs. data collection
- API Gateway pattern: Next.js acts as a proxy for Collector API
- Real-time event streaming with WebSocket + HTTP fallback
- Monorepo with shared code to avoid duplication
- Modular code organization (controllers/services/repos)
d. Key Technologies:
- Frontend: Next.js, React, Tailwind, shadcn/ui, Recharts/D3, next-intl
- Backend: Node.js, Fastify, WebSocket, SQLite
- Packaging/Deployment: pnpm workspaces, Turbo, Docker Compose, Nginx/Cloudflare

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Reverse Proxy"
        RP["Nginx/Cloudflare (Unified Domain)"]:::proxy
    end

    subgraph "Frontend Domain"
        Browser["Browser (User)"]:::external
        NextServer["Next.js UI (3000)"]:::frontend
        subgraph "Next.js Application"
            WebUI["apps/web"]:::frontend
            ProxyConfig["proxy.ts"]:::frontend
            click ProxyConfig "https://github.com/foru17/neko-master/blob/main/apps/web/proxy.ts"
            click WebUI "https://github.com/foru17/neko-master/tree/main/apps/web"
        end
        click NextServer "https://github.com/foru17/neko-master/tree/main/apps/web"
    end

    subgraph "Backend Domain"
        AppInit["app.ts (Init HTTP & WS)"]:::backend
        click AppInit "https://github.com/foru17/neko-master/blob/main/apps/collector/src/app.ts"
        FastifyAPI["Fastify API (3001)"]:::backend
        click FastifyAPI "https://github.com/foru17/neko-master/blob/main/apps/collector/src/api.ts"
        WSHandler["websocket.ts (Upgrade)"]:::backend
        click WSHandler "https://github.com/foru17/neko-master/blob/main/apps/collector/src/websocket.ts"
        WebSocketServer["WebSocket Server (3002)"]:::backend

        subgraph "Collector Modules"
            DataCollector["collector.ts"]:::backend
            click DataCollector "https://github.com/foru17/neko-master/blob/main/apps/collector/src/collector.ts"
            Cleanup["cleanup-service.ts"]:::backend
            click Cleanup "https://github.com/foru17/neko-master/blob/main/apps/collector/src/cleanup-service.ts"
            Geo["geo-service.ts"]:::backend
            click Geo "https://github.com/foru17/neko-master/blob/main/apps/collector/src/geo-service.ts"
            Retention["data-retention.ts"]:::backend
            click Retention "https://github.com/foru17/neko-master/blob/main/apps/collector/src/data-retention.ts"
        end

        subgraph "Controllers & Services"
            AuthCtrl["auth.controller.ts"]:::backend
            click AuthCtrl "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/auth/auth.controller.ts"
            AuthSrv["auth.service.ts"]:::backend
            click AuthSrv "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/auth/auth.service.ts"
            BackendCtrl["backend.controller.ts"]:::backend
            click BackendCtrl "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/backend/backend.controller.ts"
            BackendSrv["backend.service.ts"]:::backend
            click BackendSrv "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/backend/backend.service.ts"
            StatsCtrl["stats.controller.ts"]:::backend
            click StatsCtrl "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/stats/stats.controller.ts"
            StatsSrv["stats.service.ts"]:::backend
            click StatsSrv "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/stats/stats.service.ts"
            RealtimeStore["realtime.store.ts"]:::backend
            click RealtimeStore "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/realtime/realtime.store.ts"
            RealtimeMerger["realtime.merger.ts"]:::backend
            click RealtimeMerger "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/realtime/realtime.merger.ts"
            WSParser["message.parser.ts"]:::backend
            click WSParser "https://github.com/foru17/neko-master/blob/main/apps/collector/src/modules/websocket/message.parser.ts"
        end

        subgraph "Database Layer"
            DBConn["connection.ts"]:::db
            click DBConn "https://github.com/foru17/neko-master/blob/main/apps/collector/src/database/connection.ts"
            DBSchema["schema.ts"]:::db
            click DBSchema "https://github.com/foru17/neko-master/blob/main/apps/collector/src/database/schema.ts"
            BaseRepo["base.repository.ts"]:::db
            click BaseRepo "https://github.com/foru17/neko-master/blob/main/apps/collector/src/database/repositories/base.repository.ts"
            DomainRepo["domain.repository.ts"]:::db
            click DomainRepo "https://github.com/foru17/neko-master/blob/main/apps/collector/src/database/repositories/domain.repository.ts"
            BackendRepo["backend.repository.ts"]:::db
            click BackendRepo "https://github.com/foru17/neko-master/blob/main/apps/collector/src/database/repositories/backend.repository.ts"
            SQLite["stats.db"]:::db
        end
    end

    Shared["Shared Library"]:::shared
    click Shared "https://github.com/foru17/neko-master/blob/main/packages/shared/src/index.ts"

    External["External Gateways"]:::external

    RP -->|"/ -> 3000"| NextServer
    RP -->|"/_cm_ws -> 3002"| WebSocketServer

    Browser -->|"HTTP GET /"| NextServer
    NextServer -->|"REST /api → port 3001"| FastifyAPI
    NextServer -->|"WS upgrade → /_cm_ws"| WebSocketServer
    NextServer -->|"uses shared types"| Shared

    AppInit --> FastifyAPI
    AppInit --> WSHandler
    WSHandler --> WebSocketServer

    FastifyAPI --> AuthCtrl
    AuthCtrl --> AuthSrv
    FastifyAPI --> BackendCtrl
    BackendCtrl --> BackendSrv
    FastifyAPI --> StatsCtrl
    StatsCtrl --> StatsSrv
    StatsSrv --> DomainRepo
    StatsSrv --> BackendRepo
    BackendSrv --> DomainRepo

    FastifyAPI --> DataCollector
    FastifyAPI --> Cleanup
    FastifyAPI --> Geo
    FastifyAPI --> Retention

    DataCollector -->|"SQLite read/write"| SQLite
    Cleanup --> SQLite
    Geo --> SQLite
    Retention --> SQLite
    DBConn --> SQLite
    DBSchema --> SQLite
    BaseRepo --> SQLite

    RealtimeStore --> RealtimeMerger
    RealtimeMerger --> WSParser
    WSParser --> WebSocketServer

    Shared --> DataCollector
    External --> DataCollector

    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E0F8E0,stroke:#2C662D,color:#2C662D
    classDef db fill:#FFE4B5,stroke:#D2691E,color:#D2691E
    classDef external fill:#F0F0F0,stroke:#999999,color:#555555
    classDef shared fill:#F3E8FF,stroke:#7D3C98,color:#7D3C98
    classDef proxy fill:#E8E8E8,stroke:#555555,color:#333333
```
