Skip to main content

Introduction to Heimdall

Welcome to the Heimdall documentation. Heimdall is a comprehensive full-stack platform for managing stream-related data with real-time updates, robust API capabilities, and modern web applications.

What is Heimdall?​

Heimdall is a high-performance platform consisting of:

  • Rust API Backend - A blazing-fast API server with REST, GraphQL, and WebSocket support
  • Backend Dashboard - A Next.js admin dashboard for managing the platform
  • Heimdall ID - An identity and authentication service with OAuth support
  • Documentation - This comprehensive documentation site

Architecture Overview​

┌─────────────────────────────────────────────────────────────────┐
│                        Heimdall Platform                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│  │  Backend    │   │  Heimdall   │   │    Docs     │           │
│  │  Dashboard  │   │     ID      │   │   (this)    │           │
│  │  (Next.js)  │   │  (Next.js)  │   │ (Docusaurus)│           │
│  └──────┬──────┘   └──────┬──────┘   └─────────────┘           │
│         │                  │                                     │
│         │    GraphQL       │   OAuth                             │
│         │    REST          │   Sessions                          │
│         │    WebSocket     │                                     │
│         │                  │                                     │
│  ┌──────┴──────────────────┴──────────────────────────┐         │
│  │                    Rust API                         │         │
│  │     (REST + GraphQL + WebSocket + OpenAPI)          │         │
│  └─────────────────────────┬──────────────────────────┘         │
│                            │                                     │
│  ┌─────────────────────────┴──────────────────────────┐         │
│  │              PostgreSQL + Redis                     │         │
│  └─────────────────────────────────────────────────────┘         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Features​

API Capabilities​

  • REST API - Full RESTful API with HATEOAS links and OpenAPI documentation
  • GraphQL - Flexible queries with GraphiQL IDE for development
  • WebSockets - Real-time bidirectional communication for live updates
  • Swagger UI - Interactive API documentation and testing

Authentication & Authorization​

  • OAuth Support - Twitch OAuth integration via NextAuth
  • API Keys - Programmatic access with scopes and permissions
  • RBAC - Role-Based Access Control with granular permissions
  • Session Management - Secure session handling

Real-time Features​

  • Live GPS Tracking - Real-time GPS data updates
  • WebSocket Channels - Subscribe to GPS, notifications, and stats
  • Heartbeat Monitoring - Automatic connection health checks

Developer Experience​

  • Type Safety - End-to-end type safety from Rust to TypeScript
  • Auto-generated Schemas - GraphQL and OpenAPI schemas generated from code
  • Interactive Documentation - Swagger UI and GraphiQL for testing

Service URLs​

ServiceProductionDevelopment
APIhttps://api.elcto.comhttp://localhost:3000
Consolehttps://console.elcto.comhttp://localhost:3001
Heimdall IDhttps://id.elcto.comhttp://localhost:3002
Docshttps://docs.elcto.comhttp://localhost:3003

All API endpoints use the /v1 prefix (e.g., https://api.elcto.com/v1/gps).

Quick Start​

1. Development Setup​

# Clone the repository
git clone https://github.com/elcto/heimdall.git
cd heimdall

# Initialize config files
just init

# Start the dev stack (PostgreSQL, Redis, MailDev)
just stack-up

# Run database migrations
just migrate

# Start the API (in one terminal)
just watch-api

# Start the web apps (in separate terminals)
just watch-backend  # Admin dashboard at localhost:3001
just watch-id       # Identity service at localhost:3002
just watch-docs     # Documentation at localhost:3003

2. Explore the API​

Visit the interactive documentation:

3. Get an API Token​

Contact your administrator to obtain an API token for programmatic access.

4. Make Your First Request​

# Check API health
curl https://api.elcto.com/health

# Get current GPS location (requires authentication)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.elcto.com/v1/gps/current

5. Connect via WebSocket​

const ws = new WebSocket('wss://api.elcto.com/v1/ws');

ws.onopen = () => {
  // Subscribe to GPS updates
  ws.send(JSON.stringify({
    type: 'Subscribe',
    channel: 'gps'
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'Message' && message.channel === 'gps') {
    console.log('GPS Update:', JSON.parse(message.data));
  }
};

Development Commands​

Heimdall uses just as a command runner. Run just to see all available commands.

Common Commands​

CommandDescription
just initCopy example config files
just stack-upStart PostgreSQL, Redis, MailDev
just stack-downStop dev stack services
just migrateRun database migrations
just migrate-freshReset database and run migrations
just watch-apiRun API with hot reload
just watch-backendRun backend dashboard with hot reload
just watch-idRun identity service with hot reload
just schemasGenerate OpenAPI and GraphQL schemas

Database Commands​

CommandDescription
just migrate-upRun pending migrations
just migrate-downRollback last migration
just migrate-resetRollback all and re-run migrations
just migrate-statusShow migration status
just db-freshDrop, create, and migrate database

Docker Deployment​

Heimdall provides Docker images for production deployment:

# Build images locally
docker build -f docker/api.Dockerfile -t heimdall-api .
docker build -f docker/backend.Dockerfile -t heimdall-backend .
docker build -f docker/id.Dockerfile -t heimdall-id .

Container Images​

ImagePortDescription
ghcr.io/elcto/heimdall/api3000Rust API server
ghcr.io/elcto/heimdall/backend3001Admin dashboard
ghcr.io/elcto/heimdall/id3002Identity service

Technology Stack​

Backend (Rust API)​

TechnologyPurpose
Actix-webHigh-performance HTTP framework
SQLxAsync, type-safe SQL
async-graphqlGraphQL implementation
utoipaOpenAPI documentation
RedisCaching and rate limiting
PostgreSQLPrimary database

Frontend (Next.js Apps)​

TechnologyPurpose
Next.js 16React framework with App Router
React 19UI library
TypeScriptType-safe development
TailwindCSS 4Utility-first styling
NextAuthAuthentication library
Apollo ClientGraphQL client

Project Structure​

heimdall/
├── platform/
│   ├── api/              # Rust API backend
│   │   ├── src/
│   │   │   ├── graphql/  # GraphQL schema and resolvers
│   │   │   ├── handlers/ # REST API handlers
│   │   │   ├── middleware/
│   │   │   ├── models/
│   │   │   ├── routes/
│   │   │   └── websocket/
│   │   ├── templates/    # Email templates
│   │   └── Cargo.toml
│   │
│   ├── backend/          # Admin dashboard (Next.js)
│   │   ├── src/
│   │   │   ├── app/      # App Router pages
│   │   │   ├── components/
│   │   │   └── lib/
│   │   └── package.json
│   │
│   ├── id/               # Identity service (Next.js)
│   │   ├── src/
│   │   │   ├── app/      # App Router pages
│   │   │   ├── components/
│   │   │   └── lib/
│   │   └── package.json
│   │
│   ├── docs/             # Documentation (Docusaurus)
│   │   ├── docs/
│   │   └── src/
│   │
│   └── migrations/       # Database migrations (SQL)
│
├── docker/               # Dockerfiles
│   ├── api.Dockerfile
│   ├── backend.Dockerfile
│   └── id.Dockerfile
│
├── dev-stack/            # Development Docker Compose
│   ├── db.docker-compose.yml
│   └── mail.docker-compose.yml
│
├── .github/workflows/    # CI/CD workflows
├── justfile              # Command runner
├── Cargo.toml            # Rust workspace
└── pnpm-workspace.yaml   # pnpm workspace

Next Steps​

Ready to dive deeper? Here's where to go next: