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

3.0 KiB

Contributing to DataStack

Thank you for your interest in contributing to DataStack, an open-source, self-hosted real-time telemetry and event logging platform developed by Vib Tools.

We welcome bug reports, documentation improvements, and focused code contributions that align with the project's architecture and engineering standards.


1. Core Architectural Rules

Before submitting a pull request, please review AGENTS.md and ensure your changes respect these core boundaries:

  1. Single-Source-of-Truth UI Components (components/ui/ & components/layout/)
    • All /vcon/* and public views assemble shared primitives (PageShell, AdminPageHeader, SettingsPanel, Panel, StatStrip, Table, Button, Input, Modal).
    • Do not introduce isolated inline styles or non-zero border-radius/shadow overrides (--radius: 0rem, --shadow: none).
  2. Decoupled Dual-Runtime Architecture
    • Port 3000 (web): Next.js 15 App Router serving the UI, /vcon/* administration console, POST /api/events, and GET /api/export.
    • Port 4000 (ingestion): Express + Socket.IO server (server/index.js) handling WebSocket handshakes, rate limits, idempotency, and batch CSV flushing.
    • Never embed Socket.IO server handlers inside Next.js serverless routes.
  3. Storage & Database Separation
    • Collected telemetry and event payloads are written exclusively in batches to partitioned CSV files under /storage/data/{clientId}/{YYYY-MM-DD}.csv.
    • PostgreSQL (pg) is used strictly for administrator accounts (admin_users), login lockout tracking (admin_login_attempts), registered SDK clients (client_sdks), and platform settings (admin_settings).

2. Local Development Workflow

  1. Fork & Clone the Repository
    git clone https://github.com/vibtoolshq/datastack.git
    cd datastack
    npm install
    
  2. Create a Feature or Fix Branch
    git checkout -b fix/short-description
    
  3. Run the Development Services
    # Terminal 1: Next.js Web UI & Admin Console (Port 3000)
    npm run dev
    
    # Terminal 2: Socket.IO Ingestion Service (Port 4000)
    npm run server
    
  4. Verify Build & Lint Checks
    npm run lint
    npm run build
    

3. Pull Request Checklist

  • Changes are focused on a single bug fix, improvement, or documented feature.
  • npm run lint and npm run build pass with zero errors.
  • Documentation (README.md or relevant manifest.md) is updated if behavior or configuration changed.
  • No runtime CSV files (storage/data/*) or private environment secrets (.env) are committed.

4. Contact & Support