AeThex-Corporation/AeThex-OS
1
0
Fork 0
mirror of https://github.com/AeThex-Corporation/AeThex-OS.git synced 2026-04-17 22:27:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
AeThex-OS/ARCHITECTURE_GUIDE.md

545 lines
18 KiB
Markdown
Raw Permalink Blame History

# 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 ✅
Reference in a new issue View git blame Copy permalink