Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

12.2 KB
Raw Blame

AGENTS.md

Guidance for coding agents working in this monorepo. This file is the single source of truth for agent guidance — CLAUDE.md and .github/copilot-instructions.md are thin pointers to it.

Scope and Priorities

  1. Follow this file for repo-specific workflows and conventions.
  2. Follow direct user instructions over this file when they conflict.
  3. Keep changes minimal, targeted, and consistent with existing code.

Skills (task-specific workflow guides)

Reusable process checklists live in .claude/skills/*/SKILL.md (plain Markdown — usable by any tool; Claude Code loads them automatically). Consult the matching one BEFORE starting these task types:

Skill When to use
verify-changes After any edit — minimal check set per touched area
add-stats-dimension Any schema / stats-table / write-path change (several registries must change together)
release Version bumps, CHANGELOG, tagging, CI verification
ui-conventions Any UI change — i18n, dark mode, three-state views
db-conventions Queries, repositories, ClickHouse topology, debugging data drift
agent-probe-dev Anything under apps/agent (Go probe)

Repository Overview

  • Package manager: pnpm (workspace monorepo).
  • Task runner: turbo at repo root.
  • Main apps:
    • apps/web: Next.js 16 + React 19 frontend.
    • apps/collector: Fastify + WebSocket + SQLite backend service.
    • apps/agent: Go probe deployed on routers/servers (reports to the collector over HTTP).
  • Shared package:
    • packages/shared: shared TypeScript types and utility functions.

Project Map (key files)

apps/collector/src/
  database/schema.ts                     # ALL table/index DDL (single source of truth)
  database/repositories/
    traffic-writer.repository.ts         # THE traffic write path (batchUpdateTrafficStats)
    base.repository.ts                   # time keys, range routing (resolveFactTable), chain parsing
    rule.repository.ts                   # rule stats + chain-flow DAG queries
    backend.repository.ts                # backend CRUD + deleteBackendData table list
    config.repository.ts                 # retention deletes, app_config
  shared/utils/rule-name.ts              # buildRuleName — the rule naming contract
  modules/collector/                     # gateway WS clients + BatchBuffer (30s flush)
  modules/realtime/realtime.store.ts     # in-memory deltas between flushes
  modules/websocket/websocket.server.ts  # web-client WS: subscriptions, broadcast, backpressure
  modules/stats/stats.service.ts         # SQLite/ClickHouse read routing (*WithRouting)
  modules/clickhouse/                    # CH writer/reader/config (parity with SQLite reads)
  modules/app/app.ts                     # Fastify composition root + agent ingest endpoints
apps/web/
  lib/api.ts, lib/websocket.ts           # HTTP client + stats WS hook (backendId-tagged pushes)
  lib/stats-query-keys.ts                # centralized React Query keys
  messages/{zh,en}.json                  # i18n — every key in BOTH files
  components/features/                   # domain components (rules/, countries/, backend/, stats/)
  app/[locale]/dashboard/                # main dashboard route
apps/agent/
  internal/agent/runner.go               # main loop, retry/idempotency
  nekoagent                              # POSIX-sh service manager (install/upgrade/systemd/procd)
docs/
  architecture(.en).md                   # system architecture
  agent/                                 # probe docs (user-facing)
  dev/                                   # internal analysis reports (not authoritative)

Key Contracts (violating these has caused real regressions)

  1. Rule naming: multi-hop chains aggregate under the top-level policy group (last chain hop); only buildRuleName implements this. The web flow graph and gateway-rule matching key on it (regressed in v1.3.9 — see docs/dev/deep-review-2026-07.md).
  2. One traffic write path: batchUpdateTrafficStats, one atomic outer transaction. Never add a parallel write implementation.
  3. Schema changes are multi-registry: schema.ts + migration + retention + deleteBackendData + ClickHouse writer/reader parity + shared types (checklist: add-stats-dimension skill).
  4. CSV column dedup uses the delimiter-aware INSTR(','||col||',', ','||@v||',') pattern — never bare INSTR.
  5. i18n + dark mode: every user-facing string in both messages/{zh,en}.json; every light-palette Tailwind class has a dark: counterpart; inline SVG/chart colors switch on resolvedTheme.
  6. Agent protocol: payload changes bump AgentProtocolVersion (Go) and the collector's minimum in the same commit.

Environment and Toolchain

  • Node.js: project docs target Node 22.
  • TypeScript is strict across packages.
  • Module systems:
    • apps/collector and packages/shared: ESM (type: module, NodeNext).
    • apps/web: Next.js/bundler TS config.

Install and Bootstrap

  • Install dependencies: pnpm install
  • Start all apps in dev mode: pnpm dev
  • Optional helper script: ./start.sh

Build, Lint, and Test Commands

Root (all workspaces)

  • Build all packages/apps: pnpm build
  • Run lint across workspaces: pnpm lint
  • Start all dev tasks: pnpm dev

Filtered workspace commands (recommended during development)

  • Build web only: pnpm --filter @neko-master/web build
  • Build collector only: pnpm --filter @neko-master/collector build
  • Build shared only: pnpm --filter @neko-master/shared build
  • Lint web only: pnpm --filter @neko-master/web lint
  • Lint collector only: pnpm --filter @neko-master/collector lint

Tests

  • This repo currently has tests in apps/collector (Vitest).
  • Run all collector tests: pnpm --filter @neko-master/collector test
  • Watch mode: pnpm --filter @neko-master/collector test:watch

Run a single test file (important)

  • Run one test file:
    • pnpm --filter @neko-master/collector test -- src/modules/auth/auth.service.test.ts
  • Run one test file by pattern:
    • pnpm --filter @neko-master/collector test -- src/**/*.geoip-config.test.ts
  • Run a single test case by name:
    • pnpm --filter @neko-master/collector test -- -t "should validate token format"
  • Run single file + test name:
    • pnpm --filter @neko-master/collector test -- src/modules/auth/auth.service.test.ts -t "should validate token format"

Writing tests (collector)

  • Use Vitest (describe/it/expect imported from 'vitest').
  • Use createTestDatabase() and createTestBackend() from src/__tests__/helpers.ts to set up a temporary SQLite DB in beforeEach and call cleanup() in afterEach.
  • Test files live next to the code they test (e.g., auth.service.test.ts beside auth.service.ts).

Type checks and push safety

  • Collector type check: pnpm --filter @neko-master/collector exec tsc --noEmit
  • Note: .husky/pre-push runs checks when pushing to main:
    • collector tsc --noEmit
    • web build

Code Style Guidelines

General TypeScript Rules

  • Prefer explicit types on exported APIs and import type for type-only imports.
  • Keep strict-null and unknown-safe patterns; narrow with guards.
  • Avoid any; if unavoidable, keep scope tiny and document briefly.
  • Prefix intentionally unused variables/parameters with _ (e.g., _unused).
  • Prefer small pure functions for transformations and parsing logic.

ESLint Key Rules (collector)

  • no-console: console.log is forbidden — use console.info, console.warn, or console.error instead.
  • @typescript-eslint/no-unused-vars: warn-level; variables/args prefixed with _ are exempted.
  • @typescript-eslint/no-explicit-any: warn-level in source code.
  • Test files (*.test.ts, __tests__/**): no-explicit-any and no-console are turned off.

Imports and Module Boundaries

  • Keep import groups logically ordered:
    1. platform/native modules,
    2. third-party packages,
    3. workspace/internal modules.
  • Use relative imports with .js extension in ESM NodeNext packages (collector, shared).
  • In web app code, prefer alias imports via @/* for internal modules.
  • Do not create cross-app deep imports; use @neko-master/shared for shared contracts.

Formatting and Layout

  • Match local file style instead of forcing global formatting changes.
  • Existing style is not uniform, even within a single package:
    • apps/web: double quotes and semicolons.
    • apps/collector: mixed — some files use single quotes, others use double quotes. Always follow the style of the file you are editing.
    • packages/shared: single quotes and semicolons.
  • Preserve existing whitespace and line-wrap style in touched files.

Naming Conventions

  • Filenames: kebab-case (e.g., auth.service.ts, use-gateway.ts).
  • React components: PascalCase exports; file names remain kebab-case.
  • React hooks: useXxx naming.
  • Types/interfaces/enums: PascalCase.
  • Variables/functions: camelCase.
  • Environment variables/constants: UPPER_SNAKE_CASE.
  • Database-origin fields may use snake_case (is_active, created_at); preserve API contracts.

Error Handling and Logging

  • In catch, use error: unknown, then narrow via instanceof Error.
  • Return structured API errors for HTTP handlers (e.g., { error: string }) with proper status codes.
  • Add contextual logs for operational failures (network, DB, background jobs).
  • Use timeouts for external network calls where appropriate (AbortSignal.timeout(...)).
  • Prefer resilient flows (Promise.allSettled) when partial results are acceptable.

Backend (collector) Patterns

  • Keep business logic in services; route/controller handlers should stay thin.
  • Reuse repository/base-repository helpers for DB query logic.
  • Maintain backend isolation by backendId in data paths and caches.
  • For auth/security behavior, preserve cookie/token compatibility paths.
  • Fastify plugin pattern: controllers export a FastifyPluginAsync function, registered in app.ts via app.register(controller, { prefix: '/api/xxx' }). Services are injected onto the Fastify instance through declare module 'fastify' augmentation and accessed as fastify.xxxService.

Frontend (web) Patterns

  • Respect Next.js App Router conventions (app/[locale]/...).
  • Add "use client" only for client components/hooks that need it.
  • Prefer React Query hooks for server state and caching.
  • Keep API contract types aligned with @neko-master/shared and apps/web/lib/api.ts.
  • Reuse shared utility helpers (cn, formatting utilities) instead of ad-hoc duplicates.
  • i18n: uses next-intl with two locales (zh default, en).
    • Translation files: apps/web/messages/{zh,en}.json.
    • Routing config: apps/web/i18n/routing.ts.
    • Use useTranslations('namespace') in components; never hardcode user-facing strings.
  • UI components: shadcn/ui (new-york style) + Tailwind CSS v4 + lucide-react icons.
    • Base UI primitives live in apps/web/components/ui/.
    • Config: apps/web/components.json.
    • Always reuse existing UI components before creating new ones.

Shared Package Patterns

  • packages/shared should stay framework-agnostic and side-effect free.
  • Keep shared types backward compatible when possible.
  • Export shared helpers from packages/shared/src/index.ts intentionally.

Testing Expectations for Changes

  • Backend-only changes: run collector lint + targeted tests first, then full collector tests if broad.
  • Frontend-only changes: run web lint; also run web build for production-impacting changes.
  • Cross-package changes: run pnpm lint and pnpm build before final handoff when feasible.

Related Entry Files

  • CLAUDE.md (Claude Code) and .github/copilot-instructions.md (Copilot) are thin pointers to this file — keep them that way; add new guidance HERE, not there.
  • No .cursor/rules/ or .cursorrules currently exist; if added later, they must also defer to this file.

Agent Working Notes

  • Prefer minimal, surgical edits over large refactors.
  • Avoid renaming/moving files unless required by the task.