AeThex-OS/ARCHITECTURE_GUIDE.md

# AeThex-OS: Complete Architecture Guide

> **What does this thing actually DO?** And **how do all the pieces talk to each other?**

---

## 🎯 What This System Does (in Plain English)

**AeThex-OS** is a **web desktop operating system** (like Windows 95 in your browser) with:

1. **A Desktop Interface** - Windows, taskbar, Start menu, file manager, games
2. **A Programming Language (AeThex)** - Write code once, compile to Roblox/UEFN/Unity/Web
3. **An App Ecosystem** - Users write apps, publish them, others install and run them
4. **Multiple Access Methods** - Use it in browser, on phone, or as desktop launcher
5. **Real-Time Collaboration** - WebSockets sync data across all connected users

Think: **"Chrome OS meets VS Code meets Steam, with a built-in game dev language"**

---

## 🏗️ The 5 "Builds" (and How They Talk)

You asked: **"If we have 5 different builds, are they all talking to each other?"**

Yes! Here's what they are and how they communicate:

### Build 1: **Web Client** (React/Vite)
- **Location**: `client/src/`
- **What it does**: The full OS interface you see in browser
- **Runs on**: Any web browser
- **Talks to**: Server backend via REST API + WebSocket
- **Start command**: `npm run dev:client`
- **Build command**: `npm run build` → outputs to `dist/public/`

### Build 2: **Server Backend** (Express/Node.js)
- **Location**: `server/`
- **What it does**: 
  - API endpoints for auth, database, AeThex compilation
  - WebSocket server for real-time updates
  - Static file serving (hosts the built client)
- **Runs on**: Node.js server (Railway, Replit, or local)
- **Talks to**: 
  - Supabase (PostgreSQL database)
  - All clients (web, mobile, desktop) via REST + WebSocket
- **Start command**: `npm run dev` or `npm run start`
- **Exposes**: 
  - REST API: `http://localhost:5000/api/*`
  - WebSocket: `ws://localhost:5000/ws`
  - Static web app: `http://localhost:5000/`

### Build 3: **Desktop Launcher** (Tauri)
- **Location**: `src-tauri/`
- **What it does**: Standalone .exe/.app/.deb that wraps the web client
- **Runs on**: Windows, macOS, Linux (native app)
- **Talks to**: Server backend (same API as web client)
- **Start command**: `npm run dev:launcher`
- **Build command**: 
  - Windows: `npm run build:launcher:windows` → `.exe`
  - macOS: `npm run build:launcher:macos` → `.app`
  - Linux: `npm run build:launcher:linux` → `.deb`
- **Special**: Can open external URLs in system browser

### Build 4: **Mobile App** (Capacitor)
- **Location**: `android/`, `ios/`
- **What it does**: Native Android/iOS app with mobile-optimized UI
- **Runs on**: Android phones/tablets, iPhones/iPads
- **Talks to**: Server backend (same API as web client)
- **Start command**: 
  - Android: `npm run android` (opens Android Studio)
  - iOS: `npm run ios` (opens Xcode)
- **Build command**: `npm run build:mobile` → syncs to `android/` and `ios/`
- **Special Features**: 
  - Camera access
  - Biometric auth
  - Haptic feedback
  - Push notifications

### Build 5: **Compiler Packages** (Standalone npm packages)
- **Location**: `packages/aethex-cli/`, `packages/aethex-core/`
- **What it does**: 
  - AeThex language compiler (converts `.aethex` → JS/Lua/Verse/C#)
  - Standard library (Passport, SafeInput, Compliance, DataSync)
- **Runs on**: Anywhere Node.js runs (independent of OS)
- **Talks to**: Nothing (standalone tools)
- **Can be used**: 
  - Via web UI (AeThex Studio in browser)
  - Via API (`POST /api/aethex/compile`)
  - Directly from command line
- **Install globally**: `npm install -g @aethex.os/cli` (when published)
- **Usage**: `aethex compile myfile.aethex` or `aethex new my-game`

---

## 🔗 Communication Flow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                     CENTRALIZED SERVER                       │
│                   (Express + WebSocket)                      │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  REST API Endpoints                                   │  │
│  │  • /api/auth/*        - Login, logout, session       │  │
│  │  • /api/aethex/*      - Compile, publish, install    │  │
│  │  • /api/projects/*    - Project management           │  │
│  │  • /api/achievements/* - Achievements system         │  │
│  │  • /api/*             - All other features           │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  WebSocket Server                                     │  │
│  │  • Real-time metrics                                  │  │
│  │  • Live notifications                                 │  │
│  │  • Collaborative editing                              │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Database (Supabase PostgreSQL)                       │  │
│  │  • Users, profiles, passports                         │  │
│  │  • Projects, achievements, events                     │  │
│  │  • aethex_apps, app_installations, app_reviews       │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ▲
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  WEB CLIENT  │      │   DESKTOP    │      │   MOBILE     │
│   (Browser)  │      │   LAUNCHER   │      │     APP      │
│              │      │   (Tauri)    │      │ (Capacitor)  │
│  React/Vite  │      │              │      │              │
│  Port 5000   │      │  .exe/.app   │      │ Android/iOS  │
└──────────────┘      └──────────────┘      └──────────────┘
        │                     │                     │
        └─────────────────────┴─────────────────────┘
                              │
                    All use same API
                  http://localhost:5000/api/*
                  ws://localhost:5000/ws
```

### Key Points:

1. **One Server, Many Clients**: All 3 client types (web, desktop, mobile) connect to the SAME server
2. **Same API**: They all use the exact same REST endpoints and WebSocket connection
3. **Database is Shared**: All clients read/write to the same PostgreSQL database
4. **Real-Time Sync**: WebSocket broadcasts changes to all connected clients instantly

---

## 📦 What Each Build Contains

### Web Client (`dist/public/` after build)
```
dist/public/
├── index.html          # Entry point
├── assets/
│   ├── index-*.js      # React app bundle
│   ├── index-*.css     # Styles
│   └── [images/fonts]
└── [any other static assets]
```

### Desktop Launcher (after build)
```
src-tauri/target/release/
├── aethex-os.exe       # Windows
├── AeThex OS.app       # macOS
└── aethex-os           # Linux binary

Includes:
- Rust backend (Tauri core)
- WebView container
- Bundled HTML/JS/CSS from web client
- System tray integration
- Native window controls
```

### Mobile App (after sync)
```
android/
├── app/
│   └── src/main/assets/www/    # Bundled web app
└── [Android project files]

ios/
└── App/App/public/              # Bundled web app

Includes:
- Native mobile wrapper (Java/Kotlin or Swift)
- WebView container
- Bundled HTML/JS/CSS from web client
- Native plugins (camera, biometrics, etc.)
```

---

## 🔑 Key Integration Points

### 1. Authentication Flow
All clients follow the same flow:

```typescript
// POST /api/auth/login
{ username, password } → Server validates → Session cookie set

// GET /api/auth/session
Cookie sent automatically → Server verifies → User profile returned

// All clients store session cookie → Auto-authenticated on subsequent requests
```

### 2. AeThex Compilation
Users can compile AeThex code from ANY client:

```typescript
// From AeThex Studio (web/desktop/mobile):
POST /api/aethex/compile
{
  code: "journey Hello() { notify 'Hi!' }",
  target: "roblox"
}
→ Server runs compiler
→ Returns compiled Lua code

// Or directly from CLI:
$ aethex compile hello.aethex --target roblox
→ Runs local compiler (no server needed)
```

### 3. Real-Time Updates
WebSocket pushes updates to all connected clients:

```typescript
// User A publishes an app on web client
POST /api/aethex/apps → Database updated

// WebSocket broadcasts to all clients
ws.broadcast({ type: 'new_app', app: {...} })

// User B (on mobile) sees notification immediately
→ Toast: "New app published: MyGame v1.0"
```

---

## 🚀 Deployment Scenarios

### Scenario 1: Development (Your Current Setup)
```bash
# Terminal 1: Start server
npm run dev

# Terminal 2 (optional): Start client independently
npm run dev:client

# Result:
# - Server: http://localhost:5000
# - API: http://localhost:5000/api/*
# - WebSocket: ws://localhost:5000/ws
# - Client: Served by server OR separate Vite dev server
```

### Scenario 2: Production Web Deployment
```bash
# Build everything
npm run build

# Outputs:
# - dist/index.js        (server)
# - dist/public/         (client)

# Deploy to Railway/Vercel/Replit:
npm run start

# Result:
# - Live URL: https://aethex-os.railway.app
# - Everything served from one URL
```

### Scenario 3: Desktop App Distribution
```bash
# Build desktop launcher
npm run build:launcher:windows

# Output:
# - src-tauri/target/release/aethex-os.exe

# User downloads .exe → Installs → Runs
# Result:
# - Native window opens
# - Still connects to your live server: https://aethex-os.railway.app
# - OR connect to localhost if developing
```

### Scenario 4: Mobile App Store Distribution
```bash
# Build mobile assets
npm run build:mobile

# Open Android Studio
npm run android

# Build APK/AAB for Google Play
# OR
# Open Xcode
npm run ios

# Build IPA for Apple App Store

# Users download from store → App connects to live server
```

---

## 🧩 Are They "Talking to Each Other"?

**Short Answer**: They all talk to the **server**, not directly to each other.

**Long Answer**:

```
Web Client ──────┐
                 │
Desktop App ─────┼───> SERVER <───> Database
                 │
Mobile App ──────┘
```

### What Happens When User A (Web) and User B (Mobile) Interact:

1. **User A** (web browser) publishes an app
   - `POST /api/aethex/apps` → Server saves to database

2. **Server** broadcasts via WebSocket
   - `ws.broadcast({ type: 'new_app', ... })`

3. **User B** (mobile app) receives WebSocket message
   - Shows notification: "New app available!"

4. **User C** (desktop launcher) also receives message
   - Updates app store list in real-time

### They're NOT talking peer-to-peer:
- Web client doesn't know mobile app exists
- Mobile app doesn't know desktop launcher exists
- They only know about the **server**

### Benefits of This Architecture:
✅ **Simplified**: One source of truth (server + database)  
✅ **Scalable**: Add more client types without changing others  
✅ **Consistent**: All clients show the same data  
✅ **Real-Time**: WebSocket syncs everyone instantly  

---

## 📊 Current Feature Matrix

| Feature | Web | Desktop | Mobile | Notes |
|---------|-----|---------|--------|-------|
| **OS Interface** | ✅ Full | ✅ Full | ✅ Mobile UI | Different UI, same data |
| **AeThex Studio** | ✅ Desktop windows | ✅ Desktop windows | ❌ Not yet | Desktop = windowed, Mobile needs separate component |
| **App Store** | ✅ Desktop windows | ✅ Desktop windows | ❌ Not yet | Desktop = windowed, Mobile needs separate component |
| **Login/Auth** | ✅ | ✅ | ✅ | Shared session system |
| **Projects** | ✅ | ✅ | ✅ Mobile | Mobile has separate `/hub/projects` page |
| **Messaging** | ✅ | ✅ | ✅ Mobile | Mobile has separate `/hub/messaging` page |
| **Camera** | ❌ Browser API | ❌ | ✅ Native | Mobile-only feature |
| **Real-Time Sync** | ✅ WebSocket | ✅ WebSocket | ✅ WebSocket | All connected simultaneously |
| **Offline Mode** | ❌ | ❌ | ⚠️ Partial | Mobile can cache some data |

---

## 🎯 What's Missing for Full Multi-Platform Parity

### Mobile Gaps:
1. **AeThex Studio mobile UI** - Need touch-optimized code editor
2. **App Store mobile UI** - Need swipeable app cards
3. **Terminal** - Mobile needs touch-friendly terminal emulator

### Desktop Launcher Gaps:
1. **System tray features** - Minimize to tray, quick actions
2. **Auto-updates** - Update checker for launcher itself
3. **Offline mode** - Some features work without server connection

### Compiler Gaps:
1. **Verse generator** - UEFN target not yet complete
2. **C# generator** - Unity target not yet complete
3. **npm packages** - Not yet published to npm registry

---

## 🔮 How They COULD Talk Directly (Future)

### Peer-to-Peer Options (Not Implemented):

1. **WebRTC**: Direct video/audio calls between clients
   ```
   Web Client A <──WebRTC Video──> Mobile Client B
   (No server in middle for video data)
   ```

2. **IPFS/Blockchain**: Decentralized file sharing
   ```
   Desktop Client shares file → Uploaded to IPFS
   Mobile Client downloads from IPFS directly
   (Server just stores hash)
   ```

3. **Local Network Discovery**: Desktop launcher finds mobile app on same WiFi
   ```
   Desktop broadcasts: "I'm here!"
   Mobile responds: "I see you!"
   Direct connection: 192.168.1.5:8080
   ```

**Currently**: None of these are implemented. All communication goes through the server.

---

## 🛠️ Developer Workflow

### Working on Web Client:
```bash
cd /workspaces/AeThex-OS
npm run dev:client           # Vite dev server
# Edit files in client/src/
# Hot reload enabled
```

### Working on Server:
```bash
npm run dev                  # Node + tsx watch mode
# Edit files in server/
# Auto-restart on changes
```

### Working on Desktop Launcher:
```bash
npm run dev:launcher         # Tauri dev mode
# Edit files in src-tauri/ or client/src/
# Hot reload for client code
# Restart for Rust changes
```

### Working on Mobile:
```bash
npm run build:mobile         # Sync web assets to mobile
npm run android              # Open Android Studio
# Edit files in android/ or client/src/
# Rebuild and reload in emulator
```

### Working on Compiler:
```bash
cd packages/aethex-cli
node bin/aethex.js compile ../../examples/hello.aethex
# Edit files in packages/aethex-cli/src/
# Test directly with examples
```

---

## 📝 Summary: The Big Picture

**AeThex-OS is a multi-layered system:**

1. **Foundation**: PostgreSQL database (Supabase)
2. **Core**: Express server with REST API + WebSocket
3. **Interfaces**: 
   - Web client (browser)
   - Desktop launcher (native app)
   - Mobile app (iOS/Android)
4. **Toolchain**: AeThex compiler (standalone)

**They communicate via:**
- REST API for commands (login, save project, compile code)
- WebSocket for real-time updates (notifications, live data)
- Shared database for persistent storage

**They DON'T communicate:**
- Peer-to-peer (yet)
- Directly between clients
- Without the server as intermediary

**Think of it like Google apps:**
- Gmail web, Gmail mobile, Gmail desktop → All talk to Google servers
- They don't talk to each other directly
- Server keeps everyone in sync

---

## 🎮 Try It Now

### See All Builds Working Together:

1. **Start server**:
   ```bash
   npm run dev
   ```

2. **Open web client**:
   ```
   http://localhost:5000/os
   ```

3. **Open desktop launcher** (separate terminal):
   ```bash
   npm run dev:launcher
   ```

4. **Open mobile emulator**:
   ```bash
   npm run build:mobile && npm run android
   ```

5. **Test real-time sync**:
   - Log in on web client
   - Create a project
   - Watch it appear in desktop launcher immediately
   - Check mobile app - same project there too!

6. **Test AeThex compiler**:
   - Open AeThex Studio in web browser
   - Write code
   - Compile to Roblox
   - Check terminal - see API call logged
   - Desktop launcher users see same compiler output

**Result**: All 3 clients showing the same data in real-time! 🎉

---

## 🔗 Related Documentation

- [ACCESS_GUIDE.md](ACCESS_GUIDE.md) - Where to find everything
- [AETHEX_LANGUAGE_PACKAGE.md](AETHEX_LANGUAGE_PACKAGE.md) - AeThex language reference
- [LAUNCHER_README.md](LAUNCHER_README.md) - Desktop launcher details
- [PROJECT_RUNDOWN.md](PROJECT_RUNDOWN.md) - Original project overview

---

**Last Updated**: 2026-02-20  
**Status**: Fully deployed and operational ✅