Architecture

The humuus platform combines a Next.js frontend with a Nakama backend to deliver interactive, real-time educational workshop experiences.
It follows a modular, event-driven architecture optimized for scalability and low-latency collaboration.

System Overview

Communication Flow

Client Layer:

• Next.js Frontend serves the workshop interface with server-side rendering for optimal performance
• React Components provide modular, reusable UI elements for each workshop node type
• WebSocket Connection maintains persistent, bidirectional communication for real-time updates

Backend Layer:

• Nakama Server acts as the central orchestrator, handling authentication, matchmaking, and real-time message routing
• TypeScript Runtime executes custom workshop logic with full type safety
• Workshop Logic manages state synchronization, node transitions, and participant interactions

Infrastructure Layer:

• MinIO Storage provides S3-compatible object storage for uploaded files, images, and workshop assets
• PostgreSQL stores user data, workshop configurations, session history, and persistent state
• Docker Containers enable consistent deployment across development, staging, and production environments

Workshop Node System

Each workshop is composed of nodes representing individual interactive components (e.g., Slide, Quiz, Whiteboard). Nodes exist both on the backend (for logic) and the frontend (for rendering).

Node Architecture

• Backend Nodes define the behavior, state transitions, and synchronization logic:

  • Validate participant actions and inputs
  • Manage node-specific state (e.g., quiz answers, whiteboard strokes)
  • Broadcast updates to all connected clients
  • Handle timing and progression rules

• Frontend Nodes define the visual and interactive representation:

  • Render the node UI based on current state
  • Capture user interactions and send them to the backend
  • Display real-time updates from other participants
  • Provide accessibility features and responsive design

Node Lifecycle

1. Initialization: Node is created with default configuration
2. Active: Participants interact with the node, triggering state updates
3. Completion: Node reaches its end condition (timeout, manual progression, or completion criteria)
4. Transition: Workshop moves to the next node in the sequence

Data Flow

Real-time Synchronization

• Optimistic Updates: Frontend immediately reflects user actions while awaiting server confirmation
• State Reconciliation: Server broadcasts authoritative state to all clients, resolving conflicts
• Message Ordering: Nakama guarantees message order within a match, ensuring consistent state
• Reconnection Handling: Clients automatically reconnect and receive current state after network interruptions

Monorepo Structure (Turborepo)

Package Organization

• apps/web: Next.js application with workshop participant and facilitator interfaces
• apps/nakama: Nakama server with TypeScript runtime modules for workshop logic
• apps/docs: Docusaurus documentation site for developers and users
• packages/shared: Shared TypeScript types and interfaces used across frontend and backend
• packages/ui: Reusable React component library with Storybook documentation
• packages/config: Shared configuration files (ESLint, TypeScript, Tailwind)

Turborepo Benefits

• Incremental Builds: Only rebuild packages that changed
• Intelligent Caching: Share build artifacts across team members
• Parallel Execution: Run tasks across packages simultaneously
• Dependency Graph: Automatic task ordering based on package dependencies

Tech Stack Summary

Layer	Technology	Description
Frontend	Next.js 16, React 19, TypeScript	Interactive workshop UI with RSC
Styling	Tailwind CSS, shadcn/ui	Utility-first styling system
Backend	Nakama Server (TypeScript runtime)	Real-time logic & matchmaking
Storage	MinIO (S3-compatible)	File & media handling
Database	PostgreSQL 15+	Persistent data storage
Auth	Nakama Device & Email	Seamless participant login
Deployment	Docker Compose, Kubernetes	Container orchestration
Monitoring	(Planned: Prometheus, Grafana)	Observability & metrics

Security Architecture

Authentication Flow

1. Device Authentication: Anonymous users get temporary device IDs for quick access
2. Email Authentication: Optional email/password registration for persistent accounts
3. Session Management: JWT tokens with configurable expiration
4. Role-Based Access: Facilitators vs. participants have different permissions

Data Protection

• TLS/SSL: All communication encrypted in transit
• Input Validation: Backend validates all client messages before processing
• Rate Limiting: Prevents abuse and ensures fair resource allocation
• CORS Configuration: Restricts API access to authorized origins

Scalability

Horizontal Scaling

• Docker Compose for development and small deployments (single server)
• Kubernetes for production environments with multiple nodes
• Nakama's Match handler architecture supports thousands of concurrent workshop sessions
• Stateless frontend allows deployment via edge networks (e.g., Vercel, Cloudflare)

Performance Optimizations

• Server-Side Rendering: Initial page loads are fast and SEO-friendly
• Code Splitting: Only load JavaScript needed for current workshop node
• Asset Optimization: Images and media automatically optimized and cached
• Connection Pooling: Database connections reused efficiently
• CDN Integration: Static assets served from edge locations

Load Distribution

Capacity Planning

• Concurrent Users: Each Nakama instance handles ~10,000 concurrent WebSocket connections
• Workshop Sessions: ~500 active workshops per instance (depending on node complexity)
• Message Throughput: ~50,000 messages/second per instance
• Storage: MinIO scales horizontally with additional nodes

Extensibility

Adding New Node Types

1. Define node type enum and interface in packages/shared
2. Implement backend logic in apps/nakama/src/nodes
3. Create React component in apps/web/src/components/nodes
4. Register node type in workshop renderer

Plugin System (Future)

• Custom node types without modifying core codebase
• Third-party integrations (LTI, Zoom, external APIs)
• Marketplace for community-contributed nodes

info

This architecture enables low-latency collaboration and modular extensibility — ideal for dynamic, interactive learning environments. The separation of concerns between presentation and logic allows independent scaling and development of frontend and backend components.