GovSwarm V2

Enterprise-grade backend platform with RBAC, JWT auth, audit logging, and observability.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Client (Browser)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Tactical HUD│  │ Forensic Orb│  │   Operator Hub      │  │
│  │ (Metrics)   │  │  (Three.js) │  │ (Voice/Commands)    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTPS · REST/JSON · Bearer JWT
                       │ Rate Limited · Cached
┌──────────────────────┴───────────────────────────────────────┐
│                     Backend (Express 5)                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
│  │   Auth   │ │  Agent   │ │  Report  │ │ Observability  │  │
│  │(JWT/RBAC)│ │ Service  │ │ Service  │ │   Service      │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └───────┬────────┘  │
│       └──────────────┴─────────────┴────────────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
│  │ Watchdog │ │Orchest.  │ │Telemetry │ │ Cache / Rate   │  │
│  │  (3s)    │ │  (2s)    │ │ (12s)    │ │    Limiter     │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │        Prisma ORM → PostgreSQL 15 (Docker)           │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Features

• RBAC System — ADMIN / OPERATOR / VIEWER roles with granular route-level guards
• JWT Auth + Refresh — Access token (15m) + refresh token (7d) rotation with session validation
• Audit Logging — Structured JSON audit trail with correlation IDs for every mutation
• Security Event Tracking — Login attempts, failed auth, permission denials persisted to security-audit.log
• Background Jobs — Watchdog (3s health polling), Orchestrator (2s agent dispatch), Telemetry (12s metrics sync)
• OpenAPI Docs — Swagger/OpenAPI 3.0 specification at GET /api/v1/docs
• Streaming Telemetry — Real-time system metrics via REST polling with severity-colored log output
• Premium Tactical HUD — 100vh three-column layout with live metrics, forensic 3D orb, and operator command hub
• Voice-Enabled Commands — Web Speech API for hands-free vendor switching and operations
• 4-Agent Autonomous Pipeline — Planner → Coder → Tester → Reviewer for AI-assisted feature development

Setup

git clone https://github.com/Anubhav1451/GovSwarm.git
cd GovSwarm

# Backend
cd backend && npm install
npx prisma generate
npx prisma migrate deploy
npm run dev

# Frontend (separate terminal)
cd ../frontend && npm install
npm run dev

Docker

cp .env.example .env
# Edit .env with your secrets
docker compose up -d --build

Service	Image	Port
postgres	postgres:15	5432
backend	Node.js (Express)	8000
frontend	Nginx	80

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
JWT_ACCESS_SECRET	Yes	≥32 chars, random
JWT_REFRESH_SECRET	Yes	≥32 chars, random, different value
ALLOWED_ORIGINS	Yes	Comma-separated frontend URLs
PORT	No	Default 8000
NODE_ENV	Yes	development or production

See .env.example for the full list.

API

Endpoint	Method	Auth Required	Description
/health	GET	No	Liveness & readiness probes
/health/ready	GET	No	Readiness check (DB connected)
/auth/login	POST	No	Login, returns JWT pair
/auth/refresh	POST	Refresh token	Rotate access token
/auth/logout	POST	Yes	Invalidate refresh token
/metrics	GET	No	System telemetry (CPU, memory, uptime)
/api/v1/users	GET	Yes	List users (ADMIN only)
/api/v1/agents	GET	Yes	List agents
/api/v1/reports	GET	Yes	Security reports
/api/v1/organizations	GET	Yes	Organization management

Response format (all endpoints):

{
  "success": true,
  "data": { ... },
  "meta": { "timestamp": "2026-07-06T...", "requestId": "..." }
}

Security

• Helmet — Secure HTTP headers (CSP, HSTS, X-Frame-Options, etc.)
• Rate Limiting — Configurable per-IP limits via express-rate-limit
• Input Validation — Zod schemas on every mutation endpoint
• JWT Authentication — Access + refresh token rotation with bcrypt(12) password hashing
• RBAC Guards — Middleware-enforced role checks (ADMIN / OPERATOR / VIEWER)
• CORS — Origin whitelist via ALLOWED_ORIGINS env var
• Graceful Shutdown — SIGTERM/SIGINT handlers drain connections and close Prisma cleanly
• Audit Trail — Every auth event and data mutation logged to security-audit.log

See SECURITY.md for responsible disclosure policy.

CI/CD

CI (.github/workflows/ci.yml)

Triggers on push/PR to main:

1. Backend: npm ci → prisma generate → tsc --noEmit → npm test
2. Frontend: npm ci → tsc --noEmit → npm run build

Release (.github/workflows/release.yml)

Triggers on tag push v*:

1. Build backend + frontend
2. Build & push Docker images to ghcr.io
3. Create GitHub Release

Testing

# Backend (33 tests, 7 files)
cd backend && npm test

# Frontend (4 tests, 1 file)
cd frontend && npm test

Deployment

# 1. Set environment variables
# 2. Run migrations
cd backend && npx prisma migrate deploy

# 3. Build
cd backend && npm run build
cd ../frontend && npm run build

# 4. Start
cd backend && npm start

# 5. Verify
curl http://localhost:8000/health/ready

Observability

• Structured JSON logging with correlation IDs via X-Request-ID
• GET /health — Health probes (live, ready, overall status)
• GET /metrics — System telemetry (CPU, memory, uptime, request count)
• Response headers: X-Request-ID, X-Cache, X-RateLimit-Limit, X-RateLimit-Remaining
• OpenTelemetry (optional, disabled by default)

Version

v2.8.1 — Release Notes

License

MIT