docs: update architecture documentation and manifests

Refine technical documentation to reflect current architecture, component structure, and routing conventions for the vcon console.
This commit is contained in:
Team Dark Devil committed 2026-11-17 21:22:55 +06:00
1 parent bb938c33c0
commit 367dd819f8
64 files changed
+910 -2661

No files matched your search

+16 -30
View File
@@ -1,40 +1,26 @@
# AGENTS.md — Component-Only Architecture Rules & System Directives
# AGENTS.md — Architecture Rules & Engineering Conventions
## 1. Single Source of Truth Components
## 1. Single Source of Truth UI Components
- All UI design styles are designed once as reusable components in `components/ui/` and `components/layout/`.
- Pages must never implement isolated, inline styles or custom ad-hoc styling blocks.
- Spacing, colors, fonts, borders, buttons, cards, modals, and tables are defined centrally. Any design token alteration automatically cascades across all pages.
- 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 Split
## 2. Decoupled Runtime Architecture
- **Port 3000**: Next.js App Router (Frontend UI, `/vcon/*` admin console, streaming CSV export `/api/export`).
- **Port 4000**: Express.js + Socket.IO process (WebSocket handshake, JWT verification, real-time ingestion).
- **Socket.IO Rule**: Socket.IO must never reside inside Next.js serverless route handlers.
- **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 Rules
## 3. Data Storage & Persistence Rules
- **Collected Realtime Data**: Strictly stored in rotated CSV files at `/storage/data/{clientId}/{YYYY-MM-DD}.csv`.
- **Zero Database Inserts**: Per-row DB inserts are prohibited for collected data streams.
- **File Rotation**: Rotates daily or upon reaching 100MB (`-part2.csv`).
- **Redis / In-Memory Buffer**: Aggregates batches (500 events or 2000ms timer) before flushing to disk.
- **PostgreSQL / Prisma**: Exclusively dedicated to metadata, SDK registrations, and admin settings.
- **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` strictly across all shadcn and custom UI components.
- **Shadows**: None. Clean, soft, compact flat design with subtle 1px borders.
## 5. Private Development Notes
- The root `notes/` directory is local-only and must remain ignored by Git.
- `notes/` is exclusively for private development-time notes, plans, reports, and update/fix phase logs. Never put public-facing or publishable documentation, Markdown, or public information in this directory.
- Before starting any repository update, fix, or addition, record its report and plan in `notes/` first. Keep the relevant steps and phase status/logs updated there as work progresses.
## 6. Phase Implementation & Fast Single-Pass Verification Rules
- **Strict Scope Lock**: Every phase must only touch the files and targets locked in its phase specification. Never modify unrelated features or UI outside the active phase scope.
- **No Long Verification Loops**: Once a phase's code changes are applied, perform a single verification pass (`compile_applet` + `lint_applet`), update the `notes/` phase logs immediately, close the phase, and prepare for the next phase.
- **Zero Redundant Testing Loops**: Never run repetitive or unnecessary multi-round verification/test loops within the same phase. Implement the scoped patch cleanly, verify once, and close the phase directly.
- **Border Radius**: `--radius: 0rem` across all UI components.
- **Shadows**: None (`--shadow: none`). Crisp 1px borders with dark and light theme support.