Web Applications Overview

Heimdall includes multiple 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, roles, API keys, and viewing statistics.

Key Features:

User authentication via Heimdall OAuth
Dashboard with platform statistics
GPS data visualization and management
User and permission management
Role management with fine-grained permissions
API key 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 with GDPR-compliant privacy features.

Key Features:

User registration and login
Multiple OAuth providers (Twitch, Discord, YouTube, GitHub)
Two-factor authentication (TOTP)
Account management and settings
OAuth consent flows
Account linking (multiple providers)
Connected apps management
Privacy mode for sensitive data
GDPR-compliant data export
Account deletion with grace period
Password recovery
Email verification

URLs:

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

Policies (`platform/policies`)

Legal, privacy, and compliance pages with internationalization support.

Purpose: Central hub for all legal and compliance content with cookie consent management.

Key Features:

Privacy Policy
Terms of Service
Cookie Policy and consent management
Security practices documentation
FAQ pages
Internationalization (English, German)

URLs:

Production: https://policies.elcto.com
Development: http://localhost:3004

Technology Stack

All applications share a common technology stack:

Technology	Version	Purpose
Next.js	16	React framework with App Router
React	19	UI library
TypeScript	5.9+	Type-safe development
TailwindCSS	4	Utility-first styling
NextAuth	5 (Beta)	Authentication library
next-intl	-	Internationalization (i18n)
@elcto/api	-	Shared API client library
@elcto/ui	-	Shared UI component library
@elcto/cookies-consent	-	Cookie consent components
Apollo Client	-	GraphQL client (backend only)
Playwright	-	E2E testing

Shared Libraries

All applications use shared libraries from the shared/ directory:

API Client Library (`@elcto/api`)

Located at shared/api/, provides unified API clients:

REST Client - apiRequest() for REST API calls with automatic auth
GraphQL Client - graphqlRequest() and gql() for GraphQL queries
WebSocket Client - createWebSocket() for real-time communication
React Hooks - useWebSocket() for WebSocket state management
TypeScript Types - Full type coverage for all API responses

See the API Library documentation for complete details.

UI Component Library (`@elcto/ui`)

Located at shared/ui/, provides shared components:

Consistent Design - Same components and styling across apps
Design Tokens - Shared colors, spacing, and theming via CSS variables
Reusable Components - Button, Modal, Alert, Dropdown, Avatar, Toast, and more
Platform Icons - Twitch, Discord, YouTube, Kick, Steam, etc.

See the UI Library documentation for complete details.

Cookie Consent Library (`@elcto/cookies-consent`)

Located at shared/cookies-consent/, provides GDPR-compliant cookie consent:

Cookie Banner - Customizable consent banner component
Cookie Settings - Granular consent management (essential, analytics, marketing)
React Hooks - useCookieConsent() for consent state management
Translations - Multi-language support (English, German)
Integration - Easy integration with analytics and Sentry

Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                              User Browser                                 │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐          │
│  │ Backend Console │  │   Heimdall ID   │  │    Policies     │          │
│  │  (Next.js App)  │  │  (Next.js App)  │  │  (Next.js App)  │          │
│  │                 │  │                 │  │                 │          │
│  │ - Dashboard     │  │ - Login/Signup  │  │ - Privacy Policy│          │
│  │ - GPS Mgmt      │  │ - 2FA Setup     │  │ - Terms of Use  │          │
│  │ - User Mgmt     │  │ - Account Mgmt  │  │ - Cookie Policy │          │
│  │ - Role Mgmt     │  │ - Data Export   │  │ - Security Info │          │
│  │ - API Keys      │  │ - OAuth Consent │  │ - FAQ           │          │
│  │ - OAuth Apps    │  │ - Connections   │  │                 │          │
│  └────────┬────────┘  └────────┬────────┘  └─────────────────┘          │
│           │                    │                                         │
│           │  API Calls         │  Auth Flows                            │
│           │  (GraphQL/REST)    │  (NextAuth)                            │
│           │                    │                                         │
│  ┌────────┴────────────────────┴────────────────────────────────┐       │
│  │                         Rust API                              │       │
│  │              (REST + GraphQL + WebSocket + OAuth)             │       │
│  └───────────────────────────────────────────────────────────────┘       │
│                                                                           │
└──────────────────────────────────────────────────────────────────────────┘

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 (UserButton, etc.)
│   │   ├── layouts/           # Layout components
│   │   ├── providers/         # Context providers
│   │   └── ui/                # Re-exports from @elcto/ui
│   ├── contexts/              # React contexts
│   ├── hooks/                 # Custom hooks
│   ├── lib/                   # Utilities
│   │   ├── api/               # API client (GraphQL, REST, WebSocket)
│   │   └── auth/              # Auth configuration
│   └── types/                 # TypeScript types
├── public/                    # Static assets
├── src/proxy.ts               # Next.js proxy (renamed from middleware in v16)
├── 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 (2FA, export, delete)
│   │   ├── account/           # Account management
│   │   │   ├── connections/   # Connected accounts (OAuth providers)
│   │   │   ├── security/      # 2FA setup, connected apps
│   │   │   ├── settings/      # Profile, privacy, data export
│   │   │   ├── verify-email/  # Email verification
│   │   │   └── verify-email-change/
│   │   ├── 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/
│   │   ├── account/           # Account components (TwoFactorSetupModal, etc.)
│   │   ├── auth/              # Auth components (UserButton, etc.)
│   │   └── ui/                # Re-exports from @elcto/ui + app-specific
│   ├── contexts/              # React contexts (Privacy, TwoFactor, Deletion)
│   ├── hooks/                 # Custom hooks
│   ├── lib/                   # Utilities
│   │   └── api/               # API client
│   └── types/                 # TypeScript types
├── messages/                  # i18n translation files (en.json, de.json)
├── public/                    # Static assets
├── src/proxy.ts               # Next.js proxy (renamed from middleware in v16)
├── next.config.ts
├── package.json
├── playwright.config.ts       # E2E test config
├── postcss.config.mjs
└── tsconfig.json

Shared API Library

shared/api/
├── src/
│   ├── index.ts              # Main exports
│   ├── config.ts             # Configuration utilities
│   ├── clients/
│   │   ├── rest.ts           # REST client
│   │   ├── graphql.ts        # GraphQL client
│   │   └── websocket.ts      # WebSocket client
│   ├── types/
│   │   ├── rest.ts           # REST types
│   │   ├── graphql.ts        # GraphQL types
│   │   ├── websocket.ts      # WebSocket message types
│   │   ├── user.ts           # User types
│   │   └── common.ts         # Common types
│   ├── routes/
│   │   └── users.ts          # User API routes
│   └── hooks/
│       └── useWebSocket.ts   # React WebSocket hook
├── package.json
└── tsconfig.json

Shared UI Library

shared/ui/
├── src/
│   ├── components/            # React components
│   │   ├── Alert/
│   │   ├── Avatar/
│   │   ├── Badge/
│   │   ├── Banner/
│   │   ├── BlurredText/
│   │   ├── Button/
│   │   ├── Card/
│   │   ├── CodeInput/
│   │   ├── Dropdown/
│   │   ├── FloatingInput/
│   │   ├── Icons/             # Platform icons (Twitch, Discord, etc.)
│   │   ├── LoadingSpinner/
│   │   ├── Logo/
│   │   ├── Modal/
│   │   ├── Table/
│   │   ├── Toast/             # Toast notifications
│   │   └── Tooltip/
│   ├── styles/
│   │   ├── tokens.css         # CSS design tokens
│   │   └── components.css     # Component utility classes
│   ├── utils/
│   │   └── cn.ts              # Class name utility
│   └── index.ts
├── package.json
└── tsconfig.json

Policies App

platform/policies/
├── src/
│   ├── app/
│   │   ├── [locale]/          # Localized routes (en, de)
│   │   │   ├── cookies/       # Cookie policy page
│   │   │   ├── faq/           # FAQ page
│   │   │   ├── privacy/       # Privacy policy
│   │   │   ├── security/      # Security practices
│   │   │   ├── terms/         # Terms of service
│   │   │   │   └── competition/  # Competition rules
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx       # Overview/index
│   │   ├── api/               # API routes
│   │   │   ├── auth/          # NextAuth handlers
│   │   │   ├── health/        # Health check
│   │   │   └── user/          # User profile/permissions
│   │   ├── layout.tsx
│   │   └── globals.css
│   ├── components/
│   ├── lib/
│   └── types/
├── messages/                  # i18n translation files
├── public/
├── src/proxy.ts               # Next.js proxy (renamed from middleware in v16)
├── next.config.ts
├── package.json
└── 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
Policies: http://localhost:3004

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

Backend - Backend documentation
ID - Identity service documentation
UI Library - Shared UI component library (@elcto/ui)
Authentication Flow - How auth works across apps

Applications​

Backend Dashboard (platform/backend)​

Heimdall ID (platform/id)​

Policies (platform/policies)​

Technology Stack​

Shared Libraries​

API Client Library (@elcto/api)​

UI Component Library (@elcto/ui)​

Cookie Consent Library (@elcto/cookies-consent)​

Architecture​

Project Structure​

Backend Dashboard​

Heimdall ID​

Shared API Library​

Shared UI Library​

Policies App​

Development​

Prerequisites​

Running Locally​

Environment Variables​

Building for Production​

Testing​

Next Steps​

Applications

Backend Dashboard (`platform/backend`)

Heimdall ID (`platform/id`)

Policies (`platform/policies`)

Technology Stack

Shared Libraries

API Client Library (`@elcto/api`)

UI Component Library (`@elcto/ui`)

Cookie Consent Library (`@elcto/cookies-consent`)

Architecture

Project Structure

Backend Dashboard

Heimdall ID

Shared API Library

Shared UI Library

Policies App

Development

Prerequisites

Running Locally

Environment Variables

Building for Production

Testing

Next Steps