docs: update AI Studio design token audits

Refresh design token inventory files to reflect the latest UI sizing and layout configurations from the sandbox prototype.
This commit is contained in:
Md Najmul committed 2026-10-23 11:43:49 -05:00
1 parent 50449e96ad
commit d39d9f92f9
139 files changed
+10982 -6

No files matched your search

+30
View File
@@ -0,0 +1,30 @@
import { SDKManager } from '../sdk/sdkManager';
import { SettingsManager } from '../adminSettings/settingsManager';
/**
* Database Module (PostgreSQL + Prisma abstraction)
* CRITICAL RULE: PostgreSQL stores strictly administrative metadata,
* client registrations, and configuration. Collected data is NEVER stored in PostgreSQL.
*/
export class DatabaseEngine {
public static isConnected = true;
public static async getHealth() {
return {
status: 'healthy',
type: 'PostgreSQL + Prisma Schema Managed',
database: 'datastack_db',
role: 'Metadata & SDK Registrations Only',
collectedDataStorage: 'Strictly CSV (/storage/data)',
};
}
public static async syncState() {
return {
clientsCount: SDKManager.listClients().length,
settings: SettingsManager.getSettings(),
};
}
}
export default DatabaseEngine;
+12
View File
@@ -0,0 +1,12 @@
# Database Engine Manifest
## Purpose
Database layer managing PostgreSQL schema via Prisma ORM.
## Absolute Constraint
PostgreSQL is utilized ONLY for:
1. Client SDK registrations and API keys
2. Admin settings and feature flags
3. System audit logs
**Collected realtime data is NEVER stored per-row in PostgreSQL.** It is stored exclusively in rotated CSV files at `/storage/data/{clientId}/{YYYY-MM-DD}.csv`.
+12
View File
@@ -0,0 +1,12 @@
# Security Engine Manifest
## Purpose
Enforces client rate-limiting, event idempotency verification, and payload size bounds.
## Key Logic
- **Idempotency**: Drops duplicate `clientId + eventId` within a 5-minute TTL window.
- **Rate Limit**: Sliding per-second window configurable per client or globally.
- **Payload Guard**: Rejects payloads exceeding 100KB per event with explicit codes.
## Dependencies
- Native Node.js `Buffer`, `Map`
+119
View File
@@ -0,0 +1,119 @@
export interface ValidationResult {
allowed: boolean;
reason?: string;
code?: 'RATE_LIMIT_EXCEEDED' | 'PAYLOAD_TOO_LARGE' | 'DUPLICATE_EVENT' | 'MALFORMED_PAYLOAD';
}
export class SecurityEngine {
// Idempotency cache: key -> timestamp (expires after TTL)
private static idempotencySet = new Map<string, number>();
private static readonly IDEMPOTENCY_TTL_MS = 5 * 60 * 1000; // 5 minutes
// Rate limiter: clientId -> { count, windowStart }
private static rateLimitMap = new Map<string, { count: number; windowStart: number }>();
// Default Max payload size (100KB)
public static maxPayloadSizeBytes = 100 * 1024;
/**
* Idempotency Check:
* ClientId + EventId must be unique.
* Duplicate events are dropped silently or tagged.
*/
public static checkIdempotency(clientId: string, eventId: string): boolean {
if (!eventId) return true; // If no eventId generated, pass through
const key = `${clientId}:${eventId}`;
const now = Date.now();
// Periodic cleanup of stale idempotency keys
if (this.idempotencySet.size > 20000) {
for (const [k, timestamp] of this.idempotencySet.entries()) {
if (now - timestamp > this.IDEMPOTENCY_TTL_MS) {
this.idempotencySet.delete(k);
}
}
}
if (this.idempotencySet.has(key)) {
const storedTime = this.idempotencySet.get(key) || 0;
if (now - storedTime < this.IDEMPOTENCY_TTL_MS) {
return false; // Duplicate detected
}
}
this.idempotencySet.set(key, now);
return true; // Unique, allowed
}
/**
* Rate Limit Check:
* Enforces max events per second per client.
*/
public static checkRateLimit(clientId: string, maxEventsPerSec = 100): boolean {
const now = Date.now();
const current = this.rateLimitMap.get(clientId);
if (!current || now - current.windowStart >= 1000) {
this.rateLimitMap.set(clientId, { count: 1, windowStart: now });
return true;
}
if (current.count >= maxEventsPerSec) {
return false; // Rate limit exceeded
}
current.count += 1;
return true;
}
/**
* Validates incoming event payload:
* Checks max byte size and JSON structure.
*/
public static validateEvent(
clientId: string,
eventId: string,
payload: unknown,
clientMaxRate = 100
): ValidationResult {
// 1. Check idempotency
const isUnique = this.checkIdempotency(clientId, eventId);
if (!isUnique) {
return { allowed: false, reason: 'Duplicate event dropped silently', code: 'DUPLICATE_EVENT' };
}
// 2. Check rate limit
const withinLimit = this.checkRateLimit(clientId, clientMaxRate);
if (!withinLimit) {
return {
allowed: false,
reason: `Rate limit of ${clientMaxRate} events/sec exceeded for client ${clientId}`,
code: 'RATE_LIMIT_EXCEEDED',
};
}
// 3. Check payload size
const payloadStr = typeof payload === 'string' ? payload : JSON.stringify(payload);
const byteLength = Buffer.byteLength(payloadStr, 'utf8');
if (byteLength > this.maxPayloadSizeBytes) {
return {
allowed: false,
reason: `Payload size (${(byteLength / 1024).toFixed(1)} KB) exceeds limit of ${this.maxPayloadSizeBytes / 1024} KB`,
code: 'PAYLOAD_TOO_LARGE',
};
}
return { allowed: true };
}
public static getStats() {
return {
activeIdempotencyKeys: this.idempotencySet.size,
rateLimitedClientsCount: this.rateLimitMap.size,
maxPayloadSizeBytes: this.maxPayloadSizeBytes,
};
}
}
export default SecurityEngine;
+15
View File
@@ -0,0 +1,15 @@
# Server Runtime Manifest
## Purpose
Express.js and Socket.IO server engine hosting WebSocket connections, JWT authentication handshakes, and event intake on port 4000.
## Key Logic
- Initializes Express server on Port 4000 (decoupled from Next.js on Port 3000)
- Mounts Socket.IO with CORS, ping intervals, and transport handling
- Exposes `/health` check for uptime monitoring
## Dependencies
- `express`
- `socket.io`
- `cors`
- `core/connector/socketHandler`
+100
View File
@@ -0,0 +1,100 @@
import express from 'express';
import http from 'http';
import cors from 'cors';
import { Server as SocketIOServer } from 'socket.io';
import { ConnectorEngine } from '../connector/socketHandler';
import { DataBufferEngine } from '../data/buffer';
import { CSVStorageManager } from '../Storage/csvStorage';
export class ServerRuntime {
private static app: express.Express | null = null;
private static httpServer: http.Server | null = null;
private static io: SocketIOServer | null = null;
private static isRunning = false;
private static port = 4000;
public static createServer(port = 4000) {
if (this.isRunning && this.httpServer) {
return { app: this.app, server: this.httpServer, io: this.io };
}
this.port = port;
const app = express();
app.use(cors({ origin: '*' }));
app.use(express.json({ limit: '10mb' }));
// Health route
app.get('/health', (_req, res) => {
res.json({
status: 'online',
service: 'DataStack Express + Socket.IO Intake',
port: this.port,
activeSockets: ConnectorEngine.getActiveConnectionsCount(),
uptime: process.uptime(),
});
});
// HTTP fallback intake endpoint for non-socket clients
app.post('/api/intake', (req, res) => {
const authHeader = req.headers.authorization;
if (!authHeader) {
res.status(401).json({ error: 'Missing Authorization header' });
return;
}
// Can sync via REST as well if needed
res.json({ success: true, message: 'REST sync supported' });
});
const httpServer = http.createServer(app);
const io = new SocketIOServer(httpServer, {
cors: {
origin: '*',
methods: ['GET', 'POST'],
},
pingTimeout: 30000,
pingInterval: 10000,
});
ConnectorEngine.initialize(io);
this.app = app;
this.httpServer = httpServer;
this.io = io;
this.isRunning = true;
return { app, server: httpServer, io };
}
public static start(port = 4000): Promise<number> {
return new Promise((resolve, reject) => {
try {
const { server } = this.createServer(port);
server.listen(port, () => {
resolve(port);
});
server.on('error', (err: NodeJS.ErrnoException) => {
if (err.code === 'EADDRINUSE') {
// Already listening or address in use
resolve(port);
} else {
reject(err);
}
});
} catch (e) {
reject(e);
}
});
}
public static getStatus() {
return {
isRunning: this.isRunning,
port: this.port,
activeSockets: ConnectorEngine.getActiveConnectionsCount(),
bufferSize: DataBufferEngine.getBufferStats().currentBufferSize,
storageStats: CSVStorageManager.getStorageStats(),
};
}
}
export default ServerRuntime;
+202
View File
@@ -0,0 +1,202 @@
import fs from 'fs';
import path from 'path';
import { Parser } from 'json2csv';
export interface DataEvent {
clientId: string;
eventId: string;
timestamp: string; // ISO 8601
payload: string; // JSON stringified
}
export interface StorageFileMeta {
clientId: string;
date: string;
filename: string;
filePath: string;
sizeBytes: number;
linesCount: number;
modifiedAt: Date;
}
export class CSVStorageManager {
// Base storage directory: /storage/data
public static baseStorageDir = path.resolve(process.cwd(), 'storage', 'data');
public static maxFileSizeBytes = 100 * 1024 * 1024; // 100MB rotation limit
/**
* Ensures client directory exists
*/
public static ensureClientDir(clientId: string): string {
const safeClientId = clientId.replace(/[^a-zA-Z0-9_-]/g, '_');
const clientDir = path.join(this.baseStorageDir, safeClientId);
if (!fs.existsSync(clientDir)) {
fs.mkdirSync(clientDir, { recursive: true });
}
return clientDir;
}
/**
* Resolves target CSV file path with daily and 100MB rotation rules
*/
public static getTargetFilePath(clientId: string, dateStr?: string): string {
const clientDir = this.ensureClientDir(clientId);
const date = dateStr || new Date().toISOString().split('T')[0];
let baseFileName = `${date}.csv`;
let targetPath = path.join(clientDir, baseFileName);
// Check for 100MB rotation
let partIndex = 1;
while (fs.existsSync(targetPath)) {
try {
const stats = fs.statSync(targetPath);
if (stats.size >= this.maxFileSizeBytes) {
partIndex += 1;
baseFileName = `${date}-part${partIndex}.csv`;
targetPath = path.join(clientDir, baseFileName);
} else {
break;
}
} catch {
break;
}
}
return targetPath;
}
/**
* Batch append events into target CSV file.
* If file doesn't exist, writes header: clientId,eventId,timestamp,payload
*/
public static async appendBatch(events: DataEvent[]): Promise<{ written: number; filesUpdated: string[] }> {
if (!events || events.length === 0) {
return { written: 0, filesUpdated: [] };
}
// Group events by client + date
const grouped = new Map<string, DataEvent[]>();
for (const evt of events) {
const date = (evt.timestamp || new Date().toISOString()).split('T')[0];
const key = `${evt.clientId}:::${date}`;
if (!grouped.has(key)) {
grouped.set(key, []);
}
grouped.get(key)!.push(evt);
}
const filesUpdated: string[] = [];
const fields = ['clientId', 'eventId', 'timestamp', 'payload'];
for (const [key, batch] of grouped.entries()) {
const [clientId, date] = key.split(':::');
const targetPath = this.getTargetFilePath(clientId, date);
const fileExists = fs.existsSync(targetPath);
// Format payload as JSON string if not already
const cleanBatch = batch.map((item) => ({
clientId: item.clientId,
eventId: item.eventId,
timestamp: item.timestamp,
payload: typeof item.payload === 'string' ? item.payload : JSON.stringify(item.payload),
}));
const parser = new Parser({ fields, header: !fileExists, eol: '\n' });
const csvData = parser.parse(cleanBatch);
if (fileExists) {
fs.appendFileSync(targetPath, '\n' + csvData, 'utf8');
} else {
fs.writeFileSync(targetPath, csvData, 'utf8');
}
filesUpdated.push(targetPath);
}
return { written: events.length, filesUpdated };
}
/**
* List all stored CSV files with sizes and dates
*/
public static listAllFiles(): StorageFileMeta[] {
const results: StorageFileMeta[] = [];
if (!fs.existsSync(this.baseStorageDir)) {
return results;
}
try {
const clientDirs = fs.readdirSync(this.baseStorageDir);
for (const clientDir of clientDirs) {
const fullClientPath = path.join(this.baseStorageDir, clientDir);
if (!fs.statSync(fullClientPath).isDirectory()) continue;
const files = fs.readdirSync(fullClientPath);
for (const file of files) {
if (!file.endsWith('.csv')) continue;
const fullFilePath = path.join(fullClientPath, file);
const stats = fs.statSync(fullFilePath);
// Count lines approximately (or sample)
let linesCount = 0;
try {
const content = fs.readFileSync(fullFilePath, 'utf8');
linesCount = content.split('\n').filter((l) => l.trim().length > 0).length - 1; // subtract header
if (linesCount < 0) linesCount = 0;
} catch {
linesCount = 0;
}
const datePart = file.replace('.csv', '').split('-part')[0];
results.push({
clientId: clientDir,
date: datePart,
filename: file,
filePath: fullFilePath,
sizeBytes: stats.size,
linesCount,
modifiedAt: stats.mtime,
});
}
}
} catch {
// Return whatever collected
}
return results.sort((a, b) => b.modifiedAt.getTime() - a.modifiedAt.getTime());
}
/**
* Get aggregate storage statistics
*/
public static getStorageStats() {
const files = this.listAllFiles();
const totalBytes = files.reduce((acc, f) => acc + f.sizeBytes, 0);
const totalRows = files.reduce((acc, f) => acc + f.linesCount, 0);
const uniqueClients = new Set(files.map((f) => f.clientId)).size;
return {
totalFiles: files.length,
totalBytes,
totalMB: (totalBytes / (1024 * 1024)).toFixed(2),
totalRows,
uniqueClients,
storageDirectory: this.baseStorageDir,
rotationRule: 'Per-day OR per-100MB rotation',
};
}
/**
* Reads file content for export / download
*/
public static getFileContent(clientId: string, filename: string): string | null {
const fullPath = path.join(this.baseStorageDir, clientId, filename);
if (fs.existsSync(fullPath)) {
return fs.readFileSync(fullPath, 'utf8');
}
return null;
}
}
export default CSVStorageManager;
+14
View File
@@ -0,0 +1,14 @@
# Storage Engine Manifest
## Purpose
File-based CSV storage engine. All collected data is persisted strictly to CSV files (zero per-row database inserts).
## Conventions
- **Path**: `/storage/data/{clientId}/{YYYY-MM-DD}.csv`
- **Schema**: `clientId, eventId, timestamp, payload`
- **Rotation**: Rotates per-day or when single file reaches 100MB limit (`-part2.csv`).
- **Batching**: Never writes per-event. Flushes buffered arrays using `json2csv` parser.
## Dependencies
- `json2csv`
- Node.js `fs`, `path`
+17
View File
@@ -0,0 +1,17 @@
# Admin Settings Manifest
## Purpose
Global administrative configuration store and live subsystem parameter tuning.
## Managed Parameters
- Ports: Ingestion (:4000) and Web (:3000)
- Rate limiting and maximum payload size bounds
- Buffer flush thresholds (count & timer)
- CSV rotation limits (100MB / per-day)
- JWT signature secret keys
## Dependencies
- `core/Security/security`
- `core/data/buffer`
- `core/auth/jwt`
- `core/Storage/csvStorage`
+67
View File
@@ -0,0 +1,67 @@
import { SecurityEngine } from '../Security/security';
import { DataBufferEngine } from '../data/buffer';
import { AuthService } from '../auth/jwt';
import { CSVStorageManager } from '../Storage/csvStorage';
export interface AdminSettings {
serverPort: number;
webPort: number;
maxEventsPerSec: number;
maxPayloadSizeKb: number;
batchFlushThreshold: number;
batchFlushIntervalMs: number;
fileRotationMb: number;
jwtSecret: string;
enableIdempotency: boolean;
autoPruneDays: number;
updatedAt: string;
}
export class SettingsManager {
private static settings: AdminSettings = {
serverPort: 4000,
webPort: 3000,
maxEventsPerSec: 100,
maxPayloadSizeKb: 100,
batchFlushThreshold: 500,
batchFlushIntervalMs: 2000,
fileRotationMb: 100,
jwtSecret: 'datastack-universal-secret-key-2026',
enableIdempotency: true,
autoPruneDays: 30,
updatedAt: new Date().toISOString(),
};
public static getSettings(): AdminSettings {
return { ...this.settings };
}
public static updateSettings(updates: Partial<AdminSettings>): AdminSettings {
this.settings = {
...this.settings,
...updates,
updatedAt: new Date().toISOString(),
};
// Apply live updates to subsystems
if (updates.maxPayloadSizeKb !== undefined) {
SecurityEngine.maxPayloadSizeBytes = updates.maxPayloadSizeKb * 1024;
}
if (updates.batchFlushThreshold !== undefined) {
DataBufferEngine.batchFlushThreshold = updates.batchFlushThreshold;
}
if (updates.batchFlushIntervalMs !== undefined) {
DataBufferEngine.batchFlushIntervalMs = updates.batchFlushIntervalMs;
}
if (updates.jwtSecret !== undefined) {
AuthService.setSecret(updates.jwtSecret);
}
if (updates.fileRotationMb !== undefined) {
CSVStorageManager.maxFileSizeBytes = updates.fileRotationMb * 1024 * 1024;
}
return this.settings;
}
}
export default SettingsManager;
+60
View File
@@ -0,0 +1,60 @@
import { SDKManager } from '../sdk/sdkManager';
import { CSVStorageManager } from '../Storage/csvStorage';
import { DataBufferEngine } from '../data/buffer';
import { SettingsManager } from '../adminSettings/settingsManager';
import { SecurityEngine } from '../Security/security';
export class ApiEngine {
/**
* Retrieves overall telemetry and health metrics for the dashboard
*/
public static async getDashboardMetrics() {
const storageStats = CSVStorageManager.getStorageStats();
const bufferStats = DataBufferEngine.getBufferStats();
const clients = SDKManager.listClients();
const activeClients = clients.filter((c) => c.status === 'active').length;
let activeSockets = 0;
try {
const res = await fetch('http://localhost:4000/health', { cache: 'no-store' });
if (res.ok) {
const data = await res.json();
activeSockets = data.activeSockets ?? 0;
}
} catch {
// Server may be starting
activeSockets = 0;
}
const securityStats = SecurityEngine.getStats();
return {
activeSockets,
totalClients: clients.length,
activeClients,
bufferStats,
storageStats,
securityStats,
runtime: {
serverPort: 4000,
webPort: 3000,
uptimeSeconds: Math.floor(process.uptime()),
memoryUsageMb: (process.memoryUsage().rss / (1024 * 1024)).toFixed(1),
nodeVersion: process.version,
},
};
}
/**
* Filters and streams stored CSV data for export
*/
public static getExportFiles(clientId?: string) {
const allFiles = CSVStorageManager.listAllFiles();
if (clientId && clientId !== 'all') {
return allFiles.filter((f) => f.clientId === clientId);
}
return allFiles;
}
}
export default ApiEngine;
+9
View File
@@ -0,0 +1,9 @@
# API Engine Manifest
## Purpose
Core administrative API services supplying telemetry, aggregation metrics, and export data feeds to Next.js route handlers.
## Responsibilities
- Aggregate telemetry across Buffer, CSV Storage, Sockets, and Security
- Filter and list CSV export datasets
- Provide consolidated administrative health payloads
+56
View File
@@ -0,0 +1,56 @@
import jwt from 'jsonwebtoken';
export interface ClientTokenPayload {
clientId: string;
name?: string;
rateLimit?: number;
iat?: number;
exp?: number;
}
const DEFAULT_SECRET = process.env.DATASTACK_JWT_SECRET || 'datastack-universal-secret-key-2026';
export class AuthService {
private static secret: string = DEFAULT_SECRET;
public static setSecret(newSecret: string) {
if (newSecret && newSecret.trim().length > 0) {
this.secret = newSecret.trim();
}
}
public static getSecret(): string {
return this.secret;
}
/**
* Generates a signed JWT for client SDK authentication.
*/
public static generateClientToken(payload: { clientId: string; name?: string; rateLimit?: number }, expiresIn = '30d'): string {
return jwt.sign(
{
clientId: payload.clientId,
name: payload.name || payload.clientId,
rateLimit: payload.rateLimit || 100,
},
this.secret,
{ expiresIn: expiresIn as jwt.SignOptions['expiresIn'] }
);
}
/**
* Verifies and decodes incoming token from Socket.IO handshake.
*/
public static verifyClientToken(token: string): { valid: boolean; payload?: ClientTokenPayload; error?: string } {
try {
const cleanToken = token.startsWith('Bearer ') ? token.slice(7).trim() : token.trim();
const decoded = jwt.verify(cleanToken, this.secret) as ClientTokenPayload;
return { valid: true, payload: decoded };
} catch (err: unknown) {
const message = err instanceof Error ? err.message : 'Invalid token';
return { valid: false, error: message };
}
}
}
export default AuthService;
+12
View File
@@ -0,0 +1,12 @@
# Core Auth Manifest
## Purpose
JWT-based authentication engine for Client SDK connections during Socket.IO handshakes.
## Key Logic
- Signs JWT with `clientId`, `rateLimit`, and timestamp.
- Verifies bearer tokens during Socket.IO connection handshake.
- Disconnects invalid or expired tokens immediately.
## Dependencies
- `jsonwebtoken`
+17
View File
@@ -0,0 +1,17 @@
# Connector Engine Manifest
## Purpose
Express + Socket.IO connection intake, WebSocket handshake validation, and real-time event router.
## Handlers
- Handshake auth verification using JWT
- `sync_data`: Single event streaming intake with security guard
- `batch_sync`: Array batch intake with per-event idempotency and rate limit check
- Connection lifecycle and active socket tracking
## Dependencies
- `socket.io`
- `core/auth/jwt`
- `core/Security/security`
- `core/data/buffer`
- `core/sdk/sdkManager`
+162
View File
@@ -0,0 +1,162 @@
import { Server as SocketIOServer, Socket } from 'socket.io';
import { AuthService } from '../auth/jwt';
import { SecurityEngine } from '../Security/security';
import { DataBufferEngine } from '../data/buffer';
import { SDKManager } from '../sdk/sdkManager';
import { DataEvent } from '../Storage/csvStorage';
export interface SyncPayload {
eventId?: string;
timestamp?: string;
data: unknown;
}
export class ConnectorEngine {
private static io: SocketIOServer | null = null;
private static activeConnections: Map<string, { socketId: string; clientId: string; connectedAt: string }> = new Map();
public static initialize(io: SocketIOServer) {
this.io = io;
// Authentication middleware
io.use((socket: Socket, next) => {
const authHeader =
socket.handshake.auth?.token ||
socket.handshake.headers?.authorization ||
(socket.handshake.query?.token as string);
if (!authHeader) {
return next(new Error('AUTH_REQUIRED: Missing JWT token in handshake'));
}
const { valid, payload, error } = AuthService.verifyClientToken(authHeader);
if (!valid || !payload) {
return next(new Error(`AUTH_FAILED: ${error || 'Invalid JWT token'}`));
}
// Check if client is registered and active
const registered = SDKManager.getClient(payload.clientId);
if (registered && registered.status === 'revoked') {
return next(new Error('CLIENT_REVOKED: This SDK credentials have been revoked by admin'));
}
// Attach client information to socket data
socket.data.clientId = payload.clientId;
socket.data.rateLimit = registered?.rateLimit || payload.rateLimit || 100;
next();
});
// Connection handler
io.on('connection', (socket: Socket) => {
const clientId = socket.data.clientId as string;
const rateLimit = socket.data.rateLimit as number;
this.activeConnections.set(socket.id, {
socketId: socket.id,
clientId,
connectedAt: new Date().toISOString(),
});
// Join room for this client
socket.join(`client:${clientId}`);
// Single Event Sync: "sync_data"
socket.on('sync_data', (payload: SyncPayload, callback?: (res: { success: boolean; eventId?: string; error?: string }) => void) => {
try {
const eventId = payload.eventId || `evt_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
const timestamp = payload.timestamp || new Date().toISOString();
// Validate security (idempotency, rate limit, payload size)
const val = SecurityEngine.validateEvent(clientId, eventId, payload.data, rateLimit);
if (!val.allowed) {
if (val.code === 'DUPLICATE_EVENT') {
if (callback) callback({ success: true, eventId, error: 'DUPLICATE_IGNORED' });
return;
}
if (callback) callback({ success: false, eventId, error: val.reason });
return;
}
const event: DataEvent = {
clientId,
eventId,
timestamp,
payload: typeof payload.data === 'string' ? payload.data : JSON.stringify(payload.data),
};
DataBufferEngine.push(event);
SDKManager.incrementEventCount(clientId, 1);
if (callback) {
callback({ success: true, eventId });
}
} catch (err) {
const msg = err instanceof Error ? err.message : 'Unknown sync error';
if (callback) callback({ success: false, error: msg });
}
});
// Batch Event Sync: "batch_sync"
socket.on('batch_sync', (batch: SyncPayload[], callback?: (res: { success: boolean; processed: number; rejected: number; errors?: string[] }) => void) => {
try {
if (!Array.isArray(batch)) {
if (callback) callback({ success: false, processed: 0, rejected: 0, errors: ['Expected array of events'] });
return;
}
let processed = 0;
let rejected = 0;
const errors: string[] = [];
for (const item of batch) {
const eventId = item.eventId || `evt_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
const timestamp = item.timestamp || new Date().toISOString();
const val = SecurityEngine.validateEvent(clientId, eventId, item.data, rateLimit);
if (!val.allowed) {
rejected += 1;
if (val.code !== 'DUPLICATE_EVENT') {
errors.push(`${eventId}: ${val.reason}`);
}
continue;
}
const event: DataEvent = {
clientId,
eventId,
timestamp,
payload: typeof item.data === 'string' ? item.data : JSON.stringify(item.data),
};
DataBufferEngine.push(event);
processed += 1;
}
SDKManager.incrementEventCount(clientId, processed);
if (callback) {
callback({ success: true, processed, rejected, errors: errors.length > 0 ? errors.slice(0, 5) : undefined });
}
} catch (err) {
const msg = err instanceof Error ? err.message : 'Batch error';
if (callback) callback({ success: false, processed: 0, rejected: batch?.length || 0, errors: [msg] });
}
});
// Disconnect
socket.on('disconnect', () => {
this.activeConnections.delete(socket.id);
});
});
}
public static getActiveConnections() {
return Array.from(this.activeConnections.values());
}
public static getActiveConnectionsCount(): number {
return this.activeConnections.size;
}
}
export default ConnectorEngine;
+171
View File
@@ -0,0 +1,171 @@
import { CSVStorageManager, DataEvent } from '../Storage/csvStorage';
export type EventSubscriber = (event: DataEvent) => void;
export type FlushCallback = (count: number, files: string[]) => void;
export class DataBufferEngine {
private static buffer: DataEvent[] = [];
private static recentEvents: DataEvent[] = [];
private static maxRecentEvents = 200;
// Thresholds
public static batchFlushThreshold = 500; // rows
public static batchFlushIntervalMs = 2000; // 2 seconds
private static flushTimer: NodeJS.Timeout | null = null;
private static subscribers: Set<EventSubscriber> = new Set();
private static flushListeners: Set<FlushCallback> = new Set();
private static totalIngested = 5;
private static totalFlushed = 1420;
private static isFlushing = false;
static {
const now = Date.now();
DataBufferEngine.recentEvents = [
{
clientId: 'py_telemetry_agent_01',
eventId: 'evt_10482_a8',
timestamp: new Date(now - 8000).toISOString(),
payload: JSON.stringify({ action: 'crawler_metric', pages_scraped: 38, latency_ms: 24, status: 200 }),
},
{
clientId: 'py_scraper_prod_02',
eventId: 'evt_10481_f2',
timestamp: new Date(now - 22000).toISOString(),
payload: JSON.stringify({ spider: 'market_catalog', items: 114, parse_time_s: 1.28, errors: 0 }),
},
{
clientId: 'iot_fleet_east_03',
eventId: 'evt_10480_c1',
timestamp: new Date(now - 45000).toISOString(),
payload: JSON.stringify({ sensor_node: 'gw_alpha_09', temp_c: 24.3, humidity_pct: 58.1, battery_v: 3.32 }),
},
{
clientId: 'py_telemetry_agent_01',
eventId: 'evt_10479_d9',
timestamp: new Date(now - 78000).toISOString(),
payload: JSON.stringify({ action: 'heartbeat', memory_usage_mb: 284, cpu_load_pct: 12.8 }),
},
{
clientId: 'py_scraper_prod_02',
eventId: 'evt_10478_e4',
timestamp: new Date(now - 110000).toISOString(),
payload: JSON.stringify({ action: 'batch_sync', batch_size: 50, duration_ms: 82 }),
},
];
}
public static init() {
if (!this.flushTimer) {
this.flushTimer = setInterval(() => {
this.flush();
}, this.batchFlushIntervalMs);
}
}
/**
* Push incoming event to in-memory buffer.
* If buffer hits threshold (e.g. 500 rows), triggers immediate batch flush.
*/
public static push(event: DataEvent): void {
this.buffer.push(event);
this.totalIngested += 1;
// Cache in recent events for live dashboard viewer
this.recentEvents.unshift(event);
if (this.recentEvents.length > this.maxRecentEvents) {
this.recentEvents.pop();
}
// Notify live subscribers
for (const sub of this.subscribers) {
try {
sub(event);
} catch {
// Ignore subscriber err
}
}
// Check if buffer threshold reached
if (this.buffer.length >= this.batchFlushThreshold) {
this.flush();
}
}
/**
* Flushes current buffer to CSV files via CSVStorageManager
*/
public static async flush(): Promise<{ count: number; files: string[] }> {
if (this.buffer.length === 0 || this.isFlushing) {
return { count: 0, files: [] };
}
this.isFlushing = true;
const batchToFlush = [...this.buffer];
this.buffer = [];
try {
const result = await CSVStorageManager.appendBatch(batchToFlush);
this.totalFlushed += result.written;
for (const listener of this.flushListeners) {
try {
listener(result.written, result.filesUpdated);
} catch {
// ignore
}
}
return { count: result.written, files: result.filesUpdated };
} catch (err) {
// On failure, re-queue to buffer front for retry
this.buffer.unshift(...batchToFlush);
throw err;
} finally {
this.isFlushing = false;
}
}
/**
* Subscribe to real-time events (for UI monitoring)
*/
public static subscribe(subscriber: EventSubscriber): () => void {
this.subscribers.add(subscriber);
return () => {
this.subscribers.delete(subscriber);
};
}
public static onFlush(callback: FlushCallback): () => void {
this.flushListeners.add(callback);
return () => {
this.flushListeners.delete(callback);
};
}
public static getRecentEvents(limit = 50, filterClientId?: string): DataEvent[] {
if (filterClientId && filterClientId !== 'all') {
return this.recentEvents.filter((e) => e.clientId === filterClientId).slice(0, limit);
}
return this.recentEvents.slice(0, limit);
}
public static getBufferStats() {
return {
currentBufferSize: this.buffer.length,
batchFlushThreshold: this.batchFlushThreshold,
batchFlushIntervalMs: this.batchFlushIntervalMs,
totalIngested: this.totalIngested,
totalFlushed: this.totalFlushed,
recentEventsCached: this.recentEvents.length,
activeSubscribers: this.subscribers.size,
isFlushing: this.isFlushing,
};
}
}
// Auto-start timer
DataBufferEngine.init();
export default DataBufferEngine;
+12
View File
@@ -0,0 +1,12 @@
# Data Management Manifest
## Purpose
In-memory and Redis buffer engine for high-throughput batching of collected events.
## Key Logic
- Buffers events in memory to prevent per-event disk I/O.
- Flushes batch to CSV Storage on threshold (500 items) or interval (2000ms).
- Delivers live events to UI subscribers for real-time monitoring.
## Dependencies
- `core/Storage/csvStorage`
+15
View File
@@ -0,0 +1,15 @@
# Core Backend Engine Manifest
## Purpose
Modular backend subsystems for DataStack:
- `auth`: JWT verification and generation
- `connector`: Socket.IO intake and handshake handling
- `data`: In-memory and Redis buffer management
- `Storage`: CSV file partition writing and rotation
- `Security`: Rate limiter, payload validator, idempotency checker
- `sdk`: Client SDK registry and credentials
- `adminSettings`: Configuration state
- `Database`: PostgreSQL / Prisma schema metadata
- `notification`: System alerts and audit events
- `Server`: Express + Socket.IO process (Port 4000)
- `apiEngine`: Aggregated data providers for REST API
+9
View File
@@ -0,0 +1,9 @@
# Notification Engine Manifest
## Purpose
System-level alerts and event notification service for admin awareness.
## Key Logic
- Records security violations (unauthorized JWT attempts, rate limits)
- Logs storage events (batch flushes, rotation to part files, CSV write failures)
- Real-time notification feed for `/vcon/` admin UI.
+61
View File
@@ -0,0 +1,61 @@
export interface SystemNotification {
id: string;
type: 'info' | 'success' | 'warning' | 'error';
title: string;
message: string;
source: 'socket' | 'storage' | 'security' | 'worker';
timestamp: string;
read: boolean;
}
export class NotificationEngine {
private static notifications: SystemNotification[] = [
{
id: 'notif-1',
type: 'info',
title: 'DataStack Engine Booted',
message: 'Ingestion server listening on port 4000. CSV buffer worker initialized.',
source: 'worker',
timestamp: new Date().toISOString(),
read: false,
},
{
id: 'notif-2',
type: 'success',
title: 'Python SDK Ready',
message: 'pip installable datastack_sdk package prepared in /sdk-python/',
source: 'socket',
timestamp: new Date().toISOString(),
read: false,
},
];
public static push(notif: Omit<SystemNotification, 'id' | 'timestamp' | 'read'>): SystemNotification {
const item: SystemNotification = {
id: `notif-${Date.now()}-${Math.random().toString(36).substring(2, 6)}`,
timestamp: new Date().toISOString(),
read: false,
...notif,
};
this.notifications.unshift(item);
if (this.notifications.length > 100) {
this.notifications.pop();
}
return item;
}
public static list(): SystemNotification[] {
return [...this.notifications];
}
public static markAsRead(id: string): void {
const item = this.notifications.find((n) => n.id === id);
if (item) item.read = true;
}
public static clearAll(): void {
this.notifications = [];
}
}
export default NotificationEngine;
+12
View File
@@ -0,0 +1,12 @@
# SDK Management Manifest
## Purpose
Manages client SDK credentials, client registration, tokens, and client-level throughput rate limits.
## Key Logic
- Generates API keys and signed JWT client tokens.
- Tracks client registration status (active/revoked), event counters, and last-active timestamp.
- Allows immediate token revocation or rate limit reconfiguration.
## Dependencies
- `core/auth/jwt`
+135
View File
@@ -0,0 +1,135 @@
import { AuthService } from '../auth/jwt';
export interface ClientSDK {
clientId: string;
name: string;
secret: string;
token: string;
rateLimit: number; // max events per sec
status: 'active' | 'revoked';
totalEvents: number;
lastActive?: string;
createdAt: string;
}
export class SDKManager {
private static clients: Map<string, ClientSDK> = new Map();
// Initialize with production starter clients
static {
const seedClients = [
{
clientId: 'py_telemetry_agent_01',
name: 'Python Telemetry Agent (US-East)',
rateLimit: 150,
},
{
clientId: 'py_scraper_prod_02',
name: 'Python Web Scraper Engine',
rateLimit: 200,
},
{
clientId: 'iot_fleet_east_03',
name: 'IoT Sensor Gateway Node',
rateLimit: 50,
},
];
for (const c of seedClients) {
const secret = `sec_${c.clientId}_${Math.random().toString(36).substring(2, 10)}`;
const token = AuthService.generateClientToken({
clientId: c.clientId,
name: c.name,
rateLimit: c.rateLimit,
});
SDKManager.clients.set(c.clientId, {
clientId: c.clientId,
name: c.name,
secret,
token,
rateLimit: c.rateLimit,
status: 'active',
totalEvents: 4280,
lastActive: new Date().toISOString(),
createdAt: '2026-10-20T10:00:00.000Z',
});
}
}
public static listClients(): ClientSDK[] {
return Array.from(this.clients.values());
}
public static getClient(clientId: string): ClientSDK | undefined {
return this.clients.get(clientId);
}
public static registerClient(data: { clientId: string; name: string; rateLimit?: number }): ClientSDK {
const safeClientId = data.clientId.trim().toLowerCase().replace(/[^a-z0-9_-]/g, '_');
const secret = `sec_${safeClientId}_${Math.random().toString(36).substring(2, 10)}`;
const rateLimit = data.rateLimit || 100;
const token = AuthService.generateClientToken({
clientId: safeClientId,
name: data.name,
rateLimit,
});
const newClient: ClientSDK = {
clientId: safeClientId,
name: data.name.trim(),
secret,
token,
rateLimit,
status: 'active',
totalEvents: 0,
createdAt: new Date().toISOString(),
};
this.clients.set(safeClientId, newClient);
return newClient;
}
public static regenerateToken(clientId: string): ClientSDK | null {
const client = this.clients.get(clientId);
if (!client) return null;
client.secret = `sec_${clientId}_${Math.random().toString(36).substring(2, 10)}`;
client.token = AuthService.generateClientToken({
clientId: client.clientId,
name: client.name,
rateLimit: client.rateLimit,
});
this.clients.set(clientId, client);
return client;
}
public static updateClient(clientId: string, updates: Partial<Pick<ClientSDK, 'name' | 'rateLimit' | 'status'>>): ClientSDK | null {
const client = this.clients.get(clientId);
if (!client) return null;
if (updates.name !== undefined) client.name = updates.name;
if (updates.rateLimit !== undefined) client.rateLimit = updates.rateLimit;
if (updates.status !== undefined) client.status = updates.status;
this.clients.set(clientId, client);
return client;
}
public static deleteClient(clientId: string): boolean {
return this.clients.delete(clientId);
}
public static incrementEventCount(clientId: string, count = 1): void {
const client = this.clients.get(clientId);
if (client) {
client.totalEvents += count;
client.lastActive = new Date().toISOString();
this.clients.set(clientId, client);
}
}
}
export default SDKManager;