Refine technical documentation to reflect current architecture, component structure, and routing conventions for the vcon console.
2.1 KiB
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/andcomponents/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, default100MB, creating-part2.csv), and expired partitions are pruned according toautoPruneDays. - 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: 0remacross all UI components. - Shadows: None (
--shadow: none). Crisp 1px borders with dark and light theme support.