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
```powershell
# Start everything
.\start-dev.ps1
```

### Manual Setup
```powershell
# 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.**