Architecture Overview
This document provides a high-level overview of the Heimdall platform architecture.
System Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ Internet │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Client │ │ Backend │ │ Heimdall │ │ Docs │ │
│ │ Applications│ │ Dashboard │ │ ID │ │ Website │ │
│ │ (REST/WS) │ │ (Next.js) │ │ (Next.js) │ │ (Docusaurus)│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └─────────────┘ │
│ │ │ │ │
│ │ HTTPS │ HTTPS │ HTTPS │
│ │ WebSocket │ GraphQL │ OAuth │
│ │ │ REST │ │
│ │ │ │ │
│ ┌──────┴─────────────────┴─────────────────┴───────────────────────┐ │
│ │ Load Balancer │ │
│ │ (nginx / cloud LB) │ │
│ └──────────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────┴───────────────────────────────────┐ │
│ │ Rust API │ │
│ │ (Actix-web Server) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ REST API │ │ GraphQL │ │ WebSocket │ │ │
│ │ │ Handlers │ │ Resolvers │ │ Handlers │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Middleware │ │ │
│ │ │ (Auth, Rate Limiting, CORS, Logging) │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Business Logic │ │ │
│ │ │ (Services, Validation, Permissions) │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────┴───────────────────────────────────┐ │
│ │ Data Layer │ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │
│ │ │ PostgreSQL │ │ Redis │ │ │
│ │ │ (Primary Store) │ │ (Cache & Rate) │ │ │
│ │ │ │ │ │ │ │
│ │ │ - Users │ │ - Session Cache │ │ │
│ │ │ - GPS Data │ │ - Rate Limiting │ │ │
│ │ │ - API Keys │ │ - Pub/Sub │ │ │
│ │ │ - Roles/Permissions │ │ - Token Cache │ │ │
│ │ │ - OAuth Clients │ │ │ │ │
│ │ │ - Settings │ │ │ │ │
│ │ └─────────────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Component Overview
Rust API (platform/api)
The core backend service, handling all API requests.
Technology Stack:
- Framework: Actix-web 4
- Database: SQLx with PostgreSQL
- GraphQL: async-graphql
- OpenAPI: utoipa with Swagger UI
- Caching: Redis
Responsibilities:
- REST API endpoints
- GraphQL queries and mutations
- WebSocket connections for real-time updates
- Authentication and authorization
- Rate limiting
- Data persistence
Backend Dashboard (platform/backend)
Administrative interface for platform management.
Technology Stack:
- Framework: Next.js 15 (App Router)
- Language: TypeScript
- Styling: TailwindCSS
- Auth: NextAuth.js
- GraphQL: Apollo Client
Responsibilities:
- Admin dashboard
- GPS data visualization
- User management
- Settings configuration
- Developer tools
Heimdall ID (platform/id)
Identity and authentication service.
Technology Stack:
- Framework: Next.js 15 (App Router)
- Language: TypeScript
- Styling: TailwindCSS
- Auth: NextAuth.js
Responsibilities:
- User registration and login
- OAuth 2.0 provider functionality
- Account management
- Account linking
- Session management
Documentation (platform/docs)
This documentation site.
Technology Stack:
- Framework: Docusaurus 3
- Language: TypeScript/MDX
Data Flow
REST API Request Flow
Client Request
│
▼
┌─────────────┐
│ CORS │
│ Middleware │
└──────┬──────┘
│
▼
┌─────────────┐
│ Logger │
│ Middleware │
└──────┬──────┘
│
▼
┌─────────────┐
│ Auth │
│ Middleware │
└──────┬──────┘
│
▼
┌─────────────┐
│ Rate Limit │
│ Middleware │
└──────┬──────┘
│
▼
┌─────────────┐
│ Handler │
│ Function │
└──────┬──────┘
│
▼
┌─────────────┐
│ Service │
│ Layer │
└──────┬──────┘
│
▼
┌─────────────┐
│ Database │
│ Query │
└──────┬──────┘
│
▼
Response
WebSocket Connection Flow
Client Connect
│
▼
┌─────────────┐
│ WebSocket │
│ Upgrade │
└──────┬──────┘
│
▼
┌─────────────┐
│ State │
│ Manager │──────┐
└──────┬──────┘ │
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Connection │ │ Channel │
│ Handler │ │ Manager │
└──────┬──────┘ └──────┬──────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Subscribe/ │ │ Publish │
│ Unsubscribe │ │ Updates │
└─────────────┘ └─────────────┘
Database Schema
Core Tables
-- Users (managed by Heimdall ID)
User
├── id (UUID)
├── twitch_id
├── username
├── email
├── avatar_url
├── created_at
└── updated_at
-- Sessions (NextAuth)
Session
├── id (UUID)
├── user_id → User
├── session_token
├── expires
└── created_at
-- API Keys
ApiKey
├── id (UUID)
├── key (hashed)
├── name
├── description
├── user_id → User (optional)
├── scopes[]
├── is_active
├── expires_at
├── last_used_at
└── created_at
-- Roles
Role
├── id (UUID)
├── name (unique)
├── description
├── is_system
└── created_at
-- Permissions
Permission
├── id (UUID)
├── resource
├── action
├── description
└── created_at
-- GPS Data
GpsData
├── id (UUID)
├── latitude
├── longitude
├── altitude
├── speed
├── timestamp
└── created_at
-- Settings
Setting
├── key (primary)
├── value (JSON)
├── is_public
└── updated_at
-- OAuth Clients
OAuthClient
├── id (UUID)
├── client_id
├── client_secret (hashed)
├── name
├── redirect_uris[]
├── user_id → User
└── created_at
Junction Tables
UserRole (user_id, role_id)
ApiKeyRole (api_key_id, role_id)
RolePermission (role_id, permission_id)
LinkedAccount (user_id, provider, provider_account_id)
Deployment Architecture
Development
┌─────────────────────────────────────────────────────┐
│ Local Development │
├─────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ API │ │ Backend │ │ ID │ │
│ │ :3000 │ │ :3001 │ │ :3002 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └─────────────┼─────────────┘ │
│ │ │
│ ┌──────────────────┴──────────────────┐ │
│ │ Docker Compose │ │
│ │ ┌────────────┐ ┌────────────┐ │ │
│ │ │ PostgreSQL │ │ Redis │ │ │
│ │ │ :5432 │ │ :6379 │ │ │
│ │ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
Production
┌─────────────────────────────────────────────────────────────┐
│ Production Deployment │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ CDN / Edge Network │ │
│ │ (Cloudflare / Vercel Edge) │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────┴───────────────────────────┐ │
│ │ Load Balancer │ │
│ │ (nginx / Cloud LB) │ │
│ └────────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌────────────────────────┼───────────────────────────┐ │
│ │ ┌──────────┐ ┌────┴─────┐ ┌──────────┐ │ │
│ │ │ API Pod │ │ API Pod │ │ API Pod │ │ │
│ │ │ #1 │ │ #2 │ │ #3 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ (Kubernetes) │ │
│ └────────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌────────────────────────┼───────────────────────────┐ │
│ │ ┌─────────────────┐ │ ┌─────────────────┐ │ │
│ │ │ PostgreSQL │ │ │ Redis │ │ │
│ │ │ (Primary) │◄──┴──►│ (Cluster) │ │ │
│ │ └────────┬────────┘ └─────────────────┘ │ │
│ │ │ │ │
│ │ ┌────────┴────────┐ │ │
│ │ │ PostgreSQL │ │ │
│ │ │ (Replica) │ │ │
│ │ └─────────────────┘ │ │
│ │ (Managed Database) │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Next.js Apps │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Backend │ │ Heimdall ID │ │ │
│ │ │ (Vercel) │ │ (Vercel) │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Security Architecture
Authentication Layers
-
Session-based (Next.js apps via NextAuth)
- HTTP-only secure cookies
- JWT tokens with short expiry
- Automatic refresh
-
Token-based (API access)
- Bearer tokens in Authorization header
- API keys for programmatic access
- OAuth 2.0 for third-party apps
Authorization Model
Request
│
▼
┌─────────────────────┐
│ Extract Auth Token │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Lookup Token │
│ (JWT or API Key) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Get User/Key │
│ Roles │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Aggregate │
│ Permissions │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Check Permission │
│ (resource:action) │
└──────────┬──────────┘
│
┌─────┴─────┐
│ │
▼ ▼
Allow Deny
Next Steps
- Auth System - Detailed authentication architecture
- API Overview - API documentation
- Web Apps - Frontend applications