Files
DataStack/AGENTS.md
T
Team Dark Devil 367dd819f8 docs: update architecture documentation and manifests
Refine technical documentation to reflect current architecture, component structure, and routing conventions for the vcon console.
2026-11-17 21:22:55 +06:00

2.1 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.