Files
DataStack/AGENTS.md
T
Team Dark Devil 4279da45bb chore: establish cross-IDE synchronization protocol
Implement `.ai-rules`, formalize `MEMORY.md` as the source of truth, and initialize `docs/` structure to ensure consistent architectural context across development environments.
2026-11-18 07:11:11 +06:00

2.5 KiB

AGENTS.md — Architecture Rules & Engineering Conventions

1. Single Source of Truth UI Components

  • All reusable UI primitives and layout shells are maintained in components/ui/ and components/layout/.
  • Pages assemble shared components (PageShell, AdminPageHeader, SettingsPanel, Panel, StatStrip, Table, Button, Input, Modal) rather than introducing isolated ad-hoc styling.
  • Typography, spacing, colors, and borders use centralized CSS variables in app/globals.css.

2. Decoupled Runtime Architecture

  • Port 3000 (web): Next.js 15 App Router serving the public overview, /vcon/* administration console, authenticated HTTP ingestion (POST /api/events), and streaming CSV/JSON exports (GET /api/export).
  • Port 4000 (ingestion): Dedicated Express.js + Socket.IO service (server/index.js) handling WebSocket handshakes, client JWT authentication, rate limiting, idempotency deduplication, and batch CSV persistence.
  • Socket.IO Boundary: Socket.IO connections are handled exclusively by the Port 4000 service and never inside Next.js serverless route handlers.

3. Data Storage & Persistence Rules

  • Partitioned CSV Event Storage: Collected events are buffered in memory and flushed in batches to /storage/data/{clientId}/{YYYY-MM-DD}.csv.
  • Zero Per-Row Database Inserts: Event telemetry streams are never inserted per-row into PostgreSQL.
  • File Rotation & Pruning: CSV files rotate daily or when reaching the configured size threshold (fileRotationMb, default 100MB, creating -part2.csv), and expired partitions are pruned according to autoPruneDays.
  • PostgreSQL Metadata Store (pg): PostgreSQL is used strictly for administrator accounts (admin_users), login attempt tracking (admin_login_attempts), registered SDK client credentials (client_sdks), and platform configuration (admin_settings).

4. Design & Typography Tokens

  • Font Stack: "Segoe UI", "Segoe UI Web", system-ui, -apple-system, "Helvetica Neue", sans-serif.
  • Border Radius: --radius: 0rem across all UI components.
  • Shadows: None (--shadow: none). Crisp 1px borders with dark and light theme support.

5. Cross-IDE Persistent Memory (MEMORY.md & .ai-rules)

  • CRITICAL RULE: This is a multi-IDE project. Whenever any modification, update, or bug fix is completed in our session, automatically update MEMORY.md (or provide exact markdown blocks) so project context remains synchronized across VS Code, Google Antigravity, Cursor, and other IDEs (see .ai-rules).