How foru17/neko-master works
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