​

Devarno Cloud — Family Hub Infrastructure

​

Platform Overview

​

Core Architecture

Figure 1 — Devarno Cloud Core Architecture. The API Gateway terminates TLS and validates JWTs before routing to backend services. Auth Service underpins all identity flows, while the Audit Service acts as an immutable event sink connected to PostgreSQL and Redis.

Trace ID	Requirement	Rationale	Test Case
DEVARNO-ARCH-001	All inbound requests shall pass through the API Gateway for TLS termination and JWT validation	Centralises security enforcement and prevents direct backend access	TC-DEVARNO-ARCH-001
DEVARNO-ARCH-002	The Audit Service shall record all state-changing operations with 365-day retention	Supports compliance and forensic investigation for the family platform	TC-DEVARNO-ARCH-002
DEVARNO-ARCH-003	Email registration shall be restricted to the @devarno.cloud domain	Limits access to family members only	TC-DEVARNO-ARCH-003

​

Service Catalog

​

Technology Stack

• Language: Go 1.21+
• Framework: Standard library + middleware
• Database: PostgreSQL 16
• Cache: Redis 7+ (Streams, Pub/Sub)
• WebSocket: gorilla/websocket
• Virus Scanning: ClamAV

• Framework: Next.js 15 (App Router)
• Language: TypeScript 5+
• Auth: BetterAuth + plugins
• UI: shadcn/ui + Tailwind CSS 4
• Charts: Recharts

• Orchestration: Kubernetes (Flux CD GitOps)
• Gateway: Custom Go TLS gateway
• Monitoring: Prometheus, Grafana, structured logging
• Development: Docker Compose
• CI/CD: Shared GitHub Actions workflows

​

Key Features

​

1. Identity & Authentication

• BetterAuth integration for modern auth flows
• Cross-subdomain SSO with JWT tokens
• Email verification with @devarno.cloud domain restriction
• Role-based access control (RBAC)
• Session management and token refresh

​

2. Family Social Platform

• User profiles and family directory
• Real-time WebSocket chat with presence tracking
• Activity feeds and notifications
• Media upload and sharing (virus scanning)
• Profile pictures and avatars

​

3. Gaming & Engagement

• XP/leveling system
• Achievements and badges
• Leaderboards with Elo ratings
• Weekly challenges
• Progress tracking

​

4. Admin & Operations

• User management dashboard
• System health monitoring
• Audit log viewer (365-day retention)
• Configuration management
• CLI tools for automation

​

5. AI Integration

• Ollama proxy for LLM inference
• SSE streaming responses
• Prompt caching and optimization
• Model selection per user
• System prompt management

​

Infrastructure Components

​

Production (Kubernetes)

• GitOps: Flux CD for declarative deployment
• Environment Overlays: dev, staging, production
• Helm Charts: Templated service deployments
• Secrets Management: Sealed secrets / external-secrets
• Ingress: TLS termination at API gateway

​

Development (Docker Compose)

• Local environment with all services
• PostgreSQL + Redis containers
• Hot reload for Go services
• Next.js dev server with HMR
• Shared network for inter-service communication

​

CI/CD

• Shared Workflows: Reusable GitHub Actions
• Security Scanning: Trivy, gosec, npm audit
• Build Automation: Multi-stage Docker builds
• Testing: Unit tests, integration tests
• Deployment: Automatic to staging, manual to prod

​

Runbooks

1. Remote Access - SSH, file transfer, remote desktop setup
2. Tailscale VPN - Private network setup and management
3. Kubernetes Operations - Deployment, scaling, troubleshooting
4. Docker Compose - Local development environment
5. CI/CD Workflows - Pipeline configuration and automation

​

Documentation

• Software Requirements Specification (SRS) - Comprehensive requirements document
• Integration Matrix - Service dependencies and API contracts
• Infrastructure Guides - Kubernetes, Docker, CI/CD setup
• Operational Runbooks - Step-by-step procedures

​

Getting Started

​

Prerequisites

• Go 1.21+
• Node.js 20+ (for family-hub frontend)
• Docker & Docker Compose
• kubectl (for Kubernetes deployments)
• Tailscale (for VPN access)

​

Local Development

# Start all services with Docker Compose
cd infra-docker
docker-compose up -d

# Access services
# - Family Hub: http://localhost:3000
# - API Gateway: https://localhost:443
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379

​

Deployment

# Deploy to Kubernetes
cd infra-kubernetes
kubectl apply -k overlays/production/

# Check deployment status
flux get kustomizations
kubectl get pods -n devarno

​

Monitoring & Observability

• Metrics: Prometheus exporters on all Go services
• Logging: Structured JSON logs with context
• Tracing: Request ID propagation across services
• Health Checks: /health and /ready endpoints
• Dashboards: Grafana dashboards for each service

​

Security

• Email Domain Restriction: Only @devarno.cloud emails
• JWT Authentication: Short-lived access tokens
• TLS Everywhere: mTLS between services in production
• Virus Scanning: ClamAV on all media uploads
• Audit Logging: Immutable event log with 365-day retention
• RBAC: Fine-grained permission system
• Redis Pub/Sub: Secure config propagation

​

Service Templates

• template-go-service - Go microservice with middleware stack
• template-rust-service - Rust service with Cargo workspace

​

SDKs

• sdk-go - Go SDK with models, middleware, utilities, Redis helpers
• sdk-js - TypeScript SDK with API client types, WebSocket manager, auth helpers

​

Repository Structure

• devarno-cloud/family-hub - Main web application (Next.js)
• devarno-cloud/api-gateway - Edge gateway service
• devarno-cloud/auth-service - Authentication service
• devarno-cloud/chat-service - Real-time messaging
• devarno-cloud/media-service - File management
• devarno-cloud/gaming-service - XP and achievements
• devarno-cloud/config-service - User preferences
• devarno-cloud/ollama-proxy - LLM inference
• devarno-cloud/audit-service - Event logging
• devarno-cloud/infra-kubernetes - K8s manifests and Helm
• devarno-cloud/infra-docker - Docker Compose setup
• devarno-cloud/infra-ci - Shared CI/CD workflows
• devarno-cloud/sdk-go - Go shared library
• devarno-cloud/sdk-js - TypeScript shared library
• devarno-cloud/proto-contracts - Event schemas and contracts
• devarno-cloud/cli-tool - Admin CLI