neko-master AGENTS.md

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)