AeThex-Engine-Core/docs/UNIFIED_ARCHITECTURE.md

AeThex Unified Architecture

Everything in one place, connected.

Overview

The AeThex platform is a unified game engine + launcher that lets users:

• Build games with the AeThex Engine (Godot fork)
• Discover and purchase games in the Store
• Manage their game library
• Connect with friends

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         AeThex Desktop Application                          │
│                         (aethex.windows.editor.exe)                         │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                      Project Manager / Launcher                         ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐     ││
│  │  │   Home   │ │  Library │ │   Store  │ │ Downloads│ │ Friends  │     ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘     ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                           Game Editor                                   ││
│  │                   (Opens when editing a project)                        ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      │ HTTPS API
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         AeThex Cloud Services                               │
│                         (api.aethex.dev)                                    │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐                ││
│  │  Auth Service  │  │ Games Service  │  │ Social Service │                ││
│  │  /api/v1/auth  │  │ /api/v1/games  │  │ /api/v1/users  │                ││
│  └────────────────┘  └────────────────┘  └────────────────┘                ││
│                              │                                              │
│                              ▼                                              │
│                    ┌────────────────┐                                       │
│                    │   PostgreSQL   │                                       │
│                    └────────────────┘                                       │
└─────────────────────────────────────────────────────────────────────────────┘

Components

1. Desktop Application (C++)

Location: engine/

The AeThex Desktop Application is a custom Godot 4.7 fork that includes:

• Game Editor - Full Godot editor for building games
• Project Manager - Manages Godot projects
• Launcher Module - Custom module for game library, store, and social features

The launcher module is located at:

engine/modules/aethex_launcher/
├── aethex_launcher.cpp/h    - Main singleton, handles auth + API
├── data/
│   ├── game_library.cpp/h   - User's game library
│   ├── launcher_store.cpp/h - Store catalog
│   ├── friend_system.cpp/h  - Friends/social
│   ├── download_manager.cpp/h - Downloads
│   └── launcher_profile.cpp/h - User profile
├── ui/
│   ├── launcher_panel.cpp/h   - Main UI with sidebar
│   ├── library_panel.cpp/h    - Game library grid
│   ├── store_panel.cpp/h      - Store browser
│   ├── friends_panel.cpp/h    - Friends list
│   ├── downloads_panel.cpp/h  - Download queue
│   ├── profile_panel.cpp/h    - User profile
│   └── auth_panel.cpp/h       - Login/signup
└── editor/
    └── launcher_editor_plugin.cpp - Editor integration

2. Backend API (TypeScript/Node.js)

Location: services/auth-service/

The backend runs at api.aethex.dev (locally at localhost:3001):

services/auth-service/
├── src/
│   ├── index.ts                 - Express server
│   ├── controllers/
│   │   ├── authController.ts    - Auth logic
│   │   ├── userController.ts    - User/profile logic
│   │   └── gamesController.ts   - Games/store logic
│   ├── routes/
│   │   ├── auth.ts              - Auth endpoints
│   │   ├── user.ts              - User endpoints
│   │   └── games.ts             - Games endpoints
│   ├── middleware/
│   │   ├── authenticateToken.ts - JWT verification
│   │   ├── validateRequest.ts   - Input validation
│   │   └── errorHandler.ts      - Error handling
│   └── utils/
│       └── logger.ts            - Logging
├── prisma/
│   └── schema.prisma            - Database schema
├── package.json
└── docker-compose.yml           - PostgreSQL container

3. Database (PostgreSQL)

Schema:

• users - Account info
• sessions - Auth sessions
• launcher_profiles - Gamertag, level, playtime
• games - Store catalog
• user_games - Owned games
• friends - Friend relationships

API Endpoints

Authentication

POST /api/v1/auth/register   - Create account
POST /api/v1/auth/login      - Login
POST /api/v1/auth/refresh    - Refresh token
POST /api/v1/auth/logout     - Logout
GET  /api/v1/auth/me         - Get current user

Games & Store

GET  /api/v1/games           - List all games
GET  /api/v1/games/featured  - Get featured games
GET  /api/v1/games/:slug     - Get game details
POST /api/v1/games/:id/purchase - Add to library

Users

GET   /api/v1/users/profile  - Get profile
PATCH /api/v1/users/profile  - Update profile
GET   /api/v1/users/library  - User's games
GET   /api/v1/users/friends  - Friends list
POST  /api/v1/users/friends  - Send friend request

Data Flow

1. Login

User enters email/password
    → C++ auth_panel.cpp calls AethexLauncher::sign_in_with_email()
    → Makes POST to /api/v1/auth/login
    → Backend validates credentials
    → Returns JWT token + user data
    → C++ stores token, emits "authenticated" signal
    → UI updates to show logged in state

2. Library

LibraryPanel opens
    → Calls GameLibrary::load_library()
    → Loads from local cache (library.json)
    → If empty, populates demo games
    → If online, calls refresh_from_server()
    → Creates GameCard for each game

3. Store

StorePanel opens
    → Calls LauncherStore::fetch_featured()
    → Makes GET to /api/v1/games/featured
    → Backend returns game list
    → UI populates store cards

User clicks "Add to Cart"
    → Local cart state updated
    → Checkout calls /api/v1/games/:id/purchase
    → Game added to user's library

Development Setup

Quick Start

# Start everything
.\start-dev.ps1

Manual Setup

# 1. Start database (requires Docker)
cd services/auth-service
docker-compose up -d postgres

# 2. Setup backend
npm install
npx prisma generate
npx prisma migrate dev --name init
npm run seed
npm run dev  # Runs on localhost:3001

# 3. Build engine
cd engine
scons platform=windows target=editor -j8

# 4. Run
.\bin\aethex.windows.editor.x86_64.exe

Demo Account

• Email: demo@aethex.dev
• Password: DemoPass123

Offline Mode

The launcher works offline with demo data:

• Library: Has 4 demo games (AeThex Adventure, Neon Racer, etc.)
• Store: Shows 6 demo items with prices
• Profile: Works in guest mode

When online, data syncs with the backend.

Configuration

The launcher stores config at:

• Windows: %APPDATA%/Godot/aethex_launcher.cfg
• macOS: ~/Library/Application Support/Godot/aethex_launcher.cfg
• Linux: ~/.config/godot/aethex_launcher.cfg

Config includes:

• API base URL
• Auth tokens
• User preferences

Domain

All services use aethex.dev:

• Website: https://aethex.dev
• API: https://api.aethex.dev
• Docs: https://docs.aethex.dev

Summary

Everything connects in ONE flow:

                    AeThex Launcher (C++)
                           │
                ┌──────────┼──────────┐
                ▼          ▼          ▼
            Library     Store     Friends
                \          │          /
                 \         │         /
                  v        v        v
              api.aethex.dev (Node.js)
                           │
                           v
                      PostgreSQL

One executable. One backend. Everything connected.