Skip to main content

Web Applications Overview

Heimdall includes two Next.js web applications that provide user interfaces for the platform.

Applications​

Backend Dashboard (platform/backend)​

The admin dashboard for managing the Heimdall platform.

Purpose: Administrative interface for managing GPS data, users, settings, and viewing statistics.

Key Features:

  • User authentication via Twitch OAuth
  • Dashboard with platform statistics
  • GPS data visualization
  • User and permission management
  • Developer tools for OAuth app management

URLs:

  • Production: https://console.elcto.com
  • Development: http://localhost:3001

Heimdall ID (platform/id)​

The identity and authentication service.

Purpose: Centralized authentication and user account management.

Key Features:

  • User registration and login
  • Twitch OAuth integration
  • Account management
  • OAuth consent flows
  • Account linking (multiple providers)
  • Password recovery

URLs:

  • Production: https://id.elcto.com
  • Development: http://localhost:3002

Technology Stack​

Both applications share a common technology stack:

TechnologyVersionPurpose
Next.js15React framework with App Router
TypeScript5+Type-safe development
TailwindCSS4Utility-first styling
NextAuth5 (Beta)Authentication library
Apollo Client-GraphQL client (backend only)
Playwright-E2E testing

Architecture​

┌─────────────────────────────────────────────────────────────┐
│                      User Browser                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────────┐      ┌────────────────────┐        │
│  │  Backend Dashboard │      │    Heimdall ID     │        │
│  │   (Next.js App)    │      │   (Next.js App)    │        │
│  │                    │      │                    │        │
│  │ - Dashboard        │      │ - Login/Register   │        │
│  │ - GPS Management   │      │ - Account Settings │        │
│  │ - User Management  │      │ - OAuth Consent    │        │
│  │ - Developer Tools  │      │ - Account Linking  │        │
│  └─────────┬──────────┘      └─────────┬──────────┘        │
│            │                            │                   │
│            │    API Calls               │   Auth Flows     │
│            │    (GraphQL/REST)          │   (NextAuth)     │
│            │                            │                   │
│  ┌─────────┴────────────────────────────┴──────────┐       │
│  │                    Rust API                      │       │
│  │         (REST + GraphQL + WebSocket)             │       │
│  └──────────────────────────────────────────────────┘       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Project Structure​

Backend Dashboard​

platform/backend/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API routes
│   │   │   ├── auth/          # NextAuth handlers
│   │   │   └── user/          # User API endpoints
│   │   ├── auth/              # Auth pages (login, error)
│   │   ├── dashboard/         # Dashboard pages
│   │   ├── developer/         # Developer tools
│   │   │   └── oauth-apps/    # OAuth app management
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── globals.css
│   ├── components/
│   │   ├── auth/              # Auth components
│   │   ├── layouts/           # Layout components
│   │   ├── providers/         # Context providers
│   │   └── ui/                # UI components
│   ├── contexts/              # React contexts
│   ├── hooks/                 # Custom hooks
│   ├── lib/                   # Utilities
│   │   └── auth/              # Auth configuration
│   └── types/                 # TypeScript types
├── public/                    # Static assets
├── middleware.ts              # Next.js middleware
├── next.config.ts
├── package.json
├── playwright.config.ts       # E2E test config
├── postcss.config.mjs
└── tsconfig.json

Heimdall ID​

platform/id/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API routes
│   │   │   ├── auth/          # Auth handlers
│   │   │   │   └── link/      # Account linking
│   │   │   ├── oauth/         # OAuth flows
│   │   │   └── user/          # User endpoints
│   │   ├── account/           # Account management
│   │   │   └── connections/   # Connected accounts
│   │   ├── banned/            # Banned user page
│   │   ├── forgot-password/   # Password recovery
│   │   ├── login/             # Login page
│   │   ├── oauth/             # OAuth consent
│   │   │   ├── authorize/     # Authorization
│   │   │   └── consent/       # Consent screen
│   │   ├── register/          # Registration
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── globals.css
│   ├── components/
│   │   ├── auth/              # Auth components
│   │   └── ui/                # UI components
│   ├── contexts/              # React contexts
│   ├── hooks/                 # Custom hooks
│   ├── lib/                   # Utilities
│   └── types/                 # TypeScript types
├── public/                    # Static assets
├── middleware.ts              # Next.js middleware
├── next.config.ts
├── package.json
├── playwright.config.ts       # E2E test config
├── postcss.config.mjs
└── tsconfig.json

Development​

Prerequisites​

  • Node.js 20+
  • pnpm 8+
  • Running Rust API (for backend functionality)
  • PostgreSQL and Redis (for API)

Running Locally​

From the project root:

# Install dependencies
pnpm install

# Run Backend Dashboard
cd platform/backend
pnpm dev

# Run Heimdall ID (in another terminal)
cd platform/id
pnpm dev

Default ports:

  • Rust API: http://localhost:3000
  • Backend Dashboard (Console): http://localhost:3001
  • Heimdall ID: http://localhost:3002
  • Documentation: http://localhost:3003

Environment Variables​

Both apps require environment configuration:

# Copy example env file
cp .env.example .env.local

# Required variables
NEXTAUTH_URL=http://localhost:3001
NEXTAUTH_SECRET=your-secret-key
API_URL=http://localhost:3000

Building for Production​

# Build all apps
pnpm build

# Build specific app
cd platform/backend && pnpm build
cd platform/id && pnpm build

Testing​

# Run E2E tests
pnpm test:e2e

# Run with UI
pnpm test:e2e --ui

Next Steps​