Control Center Architecture

The UniPulse Control Center is a standalone internal ops dashboard that runs independently from the main Pulse application on PM2. It provides real-time infrastructure monitoring, Docker management, CI/CD tracking, and team task management.

---

Why Standalone?

The Control Center monitors Pulse's Docker containers and VPS health. If it ran inside Docker alongside Pulse, a container crash would take down the monitoring tool. By running on PM2, it survives all Docker-related failures and can be used to diagnose and recover from outages.

---

Tech Stack

Layer	Technology	Details
Frontend	React 19, Vite 7, TypeScript, shadcn/ui, Tailwind v4	Same stack as Pulse for consistency
Backend	Express 4, TypeScript	REST API + Socket.IO
Database	SQLite + Prisma (7 models)	Lightweight, no external DB dependency
Real-time	Socket.IO (3 namespaces)	Live metrics, Docker events, notifications
Process Manager	PM2	Auto-restart, memory limits, JSON logging
Auth	JWT (15m access + 7d refresh with rotation)	Google OAuth via whitelist
Reverse Proxy	Nginx	SSL, rate limiting, WebSocket proxy

---

Database Models (SQLite -- 7 Models)

Model	Purpose	Key Fields
User	Authenticated team members	email, name, role, lastLogin
Session	Active JWT sessions	userId, refreshToken, expiresAt
AuditLog	All actions logged with actor	userId, action, resource, details, timestamp
MetricSnapshot	VPS metrics history	cpu, memory, disk, network, timestamp
Setting	App configuration	key, value, updatedBy
Notification	Alerts and notifications	type, title, message, read, createdAt
Task	Kanban task tracker	title, description, status, assigneeId, priority

---

Services

Service	Responsibility	Key Functions
docker.service	Docker Engine API interaction	listContainers(), start(), stop(), restart(), remove(), logs(), stats(), inspect(), images(), systemInfo()
vps.service	System metrics collection	CPU, memory, disk, network via systeminformation library
metrics.service	Metrics collection and storage	3-second collection interval, 60-second storage interval, 30-day retention
github.service	GitHub API integration	Pull requests, workflow runs, CI stats across repos
auth.service	Authentication with token rotation	JWT 15-minute access tokens, 7-day refresh tokens with rotation
tasks.service	Kanban task management	CRUD with status transitions
notifications.service	Alert system	Create, read, dismiss notifications
audit.service	Audit trail	Log all actions with user context

Task Statuses (Kanban)

TODO -> IN_PROGRESS -> IN_REVIEW -> DONE

---

Socket.IO Namespaces

All Socket.IO connections require JWT authentication:

Namespace	Events Emitted	Frequency	Purpose
/metrics	vps:metrics	Every 3 seconds	Real-time CPU, memory, disk, network data
/docker	container:status, container:stats	On change + every 5s	Container lifecycle events and resource usage
/notifications	notification:new	On event	Real-time alert delivery

// Client connection with JWT auth
const socket = io('/metrics', {
  auth: { token: accessToken },
});

socket.on('vps:metrics', (data) => {
  // { cpu: 45.2, memory: { used: 3.2, total: 8 }, disk: [...], network: [...] }
  updateCharts(data);
});

---

Frontend Pages

Page	Route	Description
Home	/	Overview dashboard with key metrics
VPS Monitor	/vps	Real-time CPU, memory, disk, network charts
Docker Manager	/docker	Container list with actions (start, stop, restart, logs)
Social Stats	/social-stats	Social platform metrics overview
Task Tracker	/tasks	Kanban board (TODO, IN_PROGRESS, IN_REVIEW, DONE)
PR Tracking	/prs	Open PRs across repositories with review status
CI Analysis	/ci	GitHub Actions success rates, build times
Deployments	/deployments	Deployment history log
Notifications	/notifications	Alert history and management
Settings	/settings	App configuration, GitHub token, allowed emails
Login	/login	Google OAuth login

---

Authentication Flow

Email Whitelist

Only emails listed in the ALLOWED_EMAILS environment variable can access the Control Center. This is a critical security control for the ops dashboard.

---

Architecture Diagram

---

Cross-Reference

• VPS Monitoring -- metrics collection details
• Docker Management -- container operations
• CI/CD -- GitHub integration
• Control Center Setup -- installation guide
• System Overview -- how Control Center fits in the platform