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

+68
View File
@@ -0,0 +1,68 @@
# 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](https://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`](./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**
```bash
git clone https://github.com/vibtoolshq/datastack.git
cd datastack
npm install
```
2. **Create a Feature or Fix Branch**
```bash
git checkout -b fix/short-description
```
3. **Run the Development Services**
```bash
# 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**
```bash
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
- **General Inquiries**: [hello@vibtools.io](mailto:hello@vibtools.io)
- **Technical & Product Support**: [support@vibtools.io](mailto:support@vibtools.io)
- **GitHub Organization**: [https://github.com/vibtoolshq](https://github.com/vibtoolshq)
- **Website**: [https://vib.tools/](https://vib.tools/)