Files
DataStack/AGENTS.md
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

32 lines
2.5 KiB
Markdown

# 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`).