AeThex-OS/ACCESS_GUIDE.md

# AeThex-OS: Complete Access Guide 🗺️

## Where Is Everything? How Do I Access It?

### 🖥️ **Desktop/Web Access**

The main OS interface is accessed through your browser:

#### Primary Entry Points

```
http://localhost:5000/           → Auto-redirects to OS
http://localhost:5000/os         → Direct OS access (Desktop UI)
http://localhost:5000/launcher   → Desktop app launcher (Battle.net style)
```

#### What You'll See

**Desktop Mode** (default on laptop/desktop browsers):
- Full Windows 95/XP style interface
- Multi-window management
- Virtual desktops (1-4)
- Taskbar with Start menu
- Desktop icons
- **AeThex Studio** and **App Store** windows available

**Foundation vs Corporation Modes**:
- **Foundation**: Dark red theme, hacker aesthetic
- **Corporation**: Blue corporate theme, professional look
- Switch between them via Start Menu → "Switch Clearance"

---

### 📱 **Mobile Access**

The OS automatically detects mobile devices and shows a mobile-optimized interface.

#### Mobile-Specific Routes

```
http://localhost:5000/           → Mobile dashboard (auto-detected)
http://localhost:5000/camera     → Mobile camera/AR features
http://localhost:5000/notifications → Mobile notifications
```

#### Mobile Features
- Touch-optimized navigation
- Swipe gestures
- Native camera access
- Push notifications
- Haptic feedback
- Biometric authentication
- Bottom navigation bar (Ingress-style)

---

## 🗂️ Complete Route Map

### Main OS Routes

| Route | Access | Description |
|-------|--------|-------------|
| `/` | Public | Auto-detects device → OS or Mobile |
| `/os` | Public | Force desktop OS view |
| `/launcher` | Public | Desktop launcher (Battle.net style) |
| `/login` | Public | Authentication page |

### Desktop Apps (in OS)

These appear as **desktop windows** when you open the OS:

- 🚀 **AeThex Studio** - Code editor & compiler
- 🏪 **App Store** - Browse & install apps
- 🔑 **Passport** - Universal identity
- 🏆 **Achievements** - User achievements
- 📂 **Projects** - Project management
- 💼 **Opportunities** - Job board
- 📅 **Events** - Event calendar
- 💬 **Messages** - Chat/messaging
- 🛒 **Marketplace** - Buy/sell items
- ⚡ **Foundry** - Achievement mint/burn
- 🔍 **Intel** - Information hub
- 📁 **File Manager** - File browser
- 💻 **Code Gallery** - Code snippets
- 💿 **My Computer** - Drives view
- 🤖 **AeThex AI** - AI chat assistant
- ⌨️ **Terminal** - Command line
- 📊 **Analytics** - Analytics dashboard
- 📈 **System Status** - Metrics monitoring
- 🧰 **Dev Tools** - Developer utilities
- 📻 **Radio AeThex** - Music player
- 🐍 **Snake** - Classic game
- 💣 **Minesweeper** - Puzzle game
- 🍪 **Cookie Clicker** - Idle game
- 🔢 **Calculator** - Calculator app
- ⚙️ **Settings** - System settings

### Hub/Standalone Routes

| Route | Protection | Description |
|-------|-----------|-------------|
| `/hub/projects` | Protected | Projects interface |
| `/hub/messaging` | Protected | Messaging interface |
| `/hub/marketplace` | Protected | Marketplace interface |
| `/hub/file-manager` | Protected | File management |
| `/hub/code-gallery` | Protected | Code snippets |
| `/hub/notifications` | Protected | Notifications center |
| `/hub/analytics` | Protected | Analytics dashboard |
| `/hub/settings` | Protected | Settings panel |

### Admin Routes

| Route | Protection | Description |
|-------|-----------|-------------|
| `/admin` | Admin Only | Admin dashboard |
| `/admin/architects` | Admin Only | User management |
| `/admin/projects` | Admin Only | Project oversight |
| `/admin/credentials` | Admin Only | Credential management |
| `/admin/aegis` | Admin Only | Security center |
| `/admin/sites` | Admin Only | Site management |
| `/admin/logs` | Admin Only | System logs |
| `/admin/achievements` | Admin Only | Achievement editor |
| `/admin/applications` | Admin Only | Application management |
| `/admin/activity` | Admin Only | Activity monitoring |
| `/admin/notifications` | Admin Only | Notification management |

### Special Routes

| Route | Description |
|-------|-------------|
| `/os/link` | OAuth linking flow |
| `/network` | Social network/profiles |
| `/network/:slug` | User profile pages |
| `/passport` | Standalone passport view |
| `/achievements` | Standalone achievements |
| `/curriculum` | Learning curriculum |
| `/terminal` | Standalone terminal |
| `/lab` | Code lab environment |
| `/pitch` | Pitch deck viewer |
| `/builds` | Build status |

---

## 🏗️ Project Structure

### Where Things Live

```
/workspaces/AeThex-OS/
│
├── client/                       → Frontend (React + TypeScript)
│   ├── src/
│   │   ├── App.tsx              → Main router (ALL ROUTES DEFINED HERE)
│   │   ├── pages/
│   │   │   ├── os.tsx           → 🖥️ MAIN DESKTOP OS (6807 lines!)
│   │   │   ├── mobile-simple.tsx → 📱 Mobile dashboard
│   │   │   ├── launcher.tsx     → Desktop launcher
│   │   │   ├── hub/             → Hub pages (projects, messaging, etc.)
│   │   │   └── admin/           → Admin pages
│   │   │
│   │   └── components/
│   │       ├── AethexStudio.tsx → 🚀 IDE component
│   │       ├── AethexAppStore.tsx → 🏪 App Store component
│   │       ├── DesktopLauncher.tsx
│   │       ├── games/           → Game components
│   │       └── ui/              → UI library (shadcn)
│
├── server/                       → Backend (Express + Node)
│   ├── routes.ts                → 🔌 ALL API ENDPOINTS
│   ├── index.ts                 → Server entry point
│   ├── supabase.ts              → Database connection
│   └── websocket.ts             → Real-time features
│
├── shared/
│   └── schema.ts                → 📊 DATABASE SCHEMA (all tables)
│
├── packages/
│   ├── aethex-cli/              → 🔨 AeThex compiler
│   └── aethex-core/             → 📚 Standard library
│
├── migrations/                   → Database migrations
│   └── 0009_add_aethex_language_tables.sql
│
└── examples/                     → Example .aethex files
    ├── hello.aethex
    ├── auth.aethex
    └── leaderboard.aethex
```

---

## 🎯 Quick Access Matrix

### For Users

**Want to...**|**Go to...**|**What you'll see**
---|---|---
Use the OS|`/` or `/os`|Full desktop interface
Write AeThex code|Desktop → "AeThex Studio"|Code editor window
Install apps|Desktop → "App Store"|Browse apps
Launch desktop apps|`/launcher`|Battle.net-style launcher
Use on phone|`/` (auto-detects)|Mobile optimized view
Check achievements|Desktop → "Achievements"|Trophy collection
Manage projects|Desktop → "Projects"|Project dashboard
Send messages|Desktop → "Messages"|Chat interface
Access terminal|Desktop → "Terminal"|Command line

### For Developers

**Want to...**|**Edit file...**|**Location**
---|---|---
Add new route|`client/src/App.tsx`|Line 64+
Add desktop app|`client/src/pages/os.tsx`|`foundationApps` array (line 573)
Add API endpoint|`server/routes.ts`|`registerRoutes` function
Add database table|`shared/schema.ts`|Add new `pgTable`
Add component|`client/src/components/`|Create new .tsx file
Modify compiler|`packages/aethex-cli/src/`|Compiler source

---

## 📱 Mobile: Current State & Future

### ✅ Currently Available on Mobile

1. **Auto-Detection**: Desktop site automatically shows mobile UI
2. **Bottom Navigation**: Ingress-style hexagonal buttons
3. **Touch Optimized**: Swipe gestures and haptics
4. **Native Features**:
   - Camera access
   - Biometric auth
   - Push notifications
   - Status bar control

### 🚧 AeThex Studio/App Store on Mobile

**Current Limitation**: Studio and App Store are optimized for desktop windows.

**Mobile Solutions**:

#### Option 1: Responsive Components (Quick)
Make existing Studio/Store components responsive:
- Collapse to single column on mobile
- Use mobile-optimized Monaco editor
- Touch-friendly compile buttons

#### Option 2: Mobile-Specific Routes (Better)
Create dedicated mobile routes:
```
/mobile/studio     → Mobile-optimized code editor
/mobile/appstore   → Mobile app browser
```

#### Option 3: Progressive Web App (Best)
Install as native app:
- Home screen icon
- Offline support
- Full-screen mode
- Native-like experience

---

## 🔧 How to Add AeThex Studio to Mobile

### Quick Implementation

Add mobile routes to [client/src/App.tsx](client/src/App.tsx):

```tsx
<Route path="/mobile/studio" component={MobileAethexStudio} />
<Route path="/mobile/appstore" component={MobileAethexAppStore} />
```

Create mobile components in `client/src/pages/`:

```tsx
// mobile-aethex-studio.tsx
import AethexStudio from "@/components/AethexStudio";

export default function MobileAethexStudio() {
  return (
    <div className="h-screen overflow-auto">
      <AethexStudio />
    </div>
  );
}
```

Add navigation buttons in [mobile-simple.tsx](client/src/pages/mobile-simple.tsx):

```tsx
<QuickTile 
  icon={<Rocket className="w-7 h-7" />} 
  label="AeThex Studio" 
  color="from-purple-900/40 to-pink-900/40" 
  onPress={() => handleNav('/mobile/studio')} 
/>
<QuickTile 
  icon={<Store className="w-7 h-7" />} 
  label="App Store" 
  color="from-blue-900/40 to-cyan-900/40" 
  onPress={() => handleNav('/mobile/appstore')} 
/>
```

---

## 🎮 Testing URLs

### Development Server

```bash
npm run dev
```

Then visit:

- **Desktop OS**: http://localhost:5000/os
- **Mobile Dashboard**: http://localhost:5000/ (on phone)
- **Launcher**: http://localhost:5000/launcher
- **Login**: http://localhost:5000/login
- **Admin**: http://localhost:5000/admin

### Chrome DevTools Mobile Testing

1. Press `F12` to open DevTools
2. Click device icon (toggle device toolbar)
3. Select "iPhone 14 Pro" or similar
4. Reload page
5. See mobile interface!

---

## 📊 Database Access

### Supabase Dashboard

Your database is hosted on Supabase. Access via:

```
https://app.supabase.com
```

**Tables for AeThex Apps**:
- `aethex_apps` - All user-created apps
- `aethex_app_installations` - Who installed what
- `aethex_app_reviews` - Ratings & reviews

### Run Migrations

```bash
# Apply new migrations
npm run db:migrate

# Or manually with Supabase CLI
npx supabase migration up
```

---

## 🗝️ Key Files You'll Edit Often

### Frontend

File|Purpose|When to Edit
---|---|---
`client/src/App.tsx`|Router config|Adding new routes
`client/src/pages/os.tsx`|Main OS|Adding desktop apps
`client/src/components/AethexStudio.tsx`|Code editor|Modifying IDE
`client/src/components/AethexAppStore.tsx`|App browser|Modifying store

### Backend

File|Purpose|When to Edit
---|---|---
`server/routes.ts`|API endpoints|Adding new APIs
`server/index.ts`|Server setup|Changing server config
`shared/schema.ts`|Database schema|Adding tables/fields

### Compiler

File|Purpose|When to Edit
---|---|---
`packages/aethex-cli/src/compiler/Lexer.ts`|Tokenizer|Adding keywords
`packages/aethex-cli/src/compiler/Parser.ts`|AST builder|Changing syntax
`packages/aethex-cli/src/compiler/JavaScriptGenerator.ts`|JS output|JS code generation
`packages/aethex-cli/src/compiler/LuaGenerator.ts`|Lua output|Roblox code generation

---

## 🚀 Quick Start Commands

```bash
# Start development server
npm run dev

# Build everything
npm run build

# Run migrations
npm run db:migrate

# Compile AeThex code directly
cd packages/aethex-cli
node bin/aethex.js compile ../../examples/hello.aethex

# Test the output
node -e "$(cat ../../examples/hello.js); Main();"
```

---

## 🎯 Common Tasks

### Task: Add a New Desktop App

1. Edit [client/src/pages/os.tsx](client/src/pages/os.tsx)
2. Find `foundationApps` array (line ~573)
3. Add your app:
   ```tsx
   { 
     id: "myapp", 
     title: "My App", 
     icon: <Code className="w-8 h-8" />, 
     component: "myapp", 
     defaultWidth: 800, 
     defaultHeight: 600 
   }
   ```
4. Add render case in `renderAppContent` (line ~839):
   ```tsx
   case 'myapp': return <MyAppComponent />;
   ```

### Task: Add Mobile Route

1. Edit [client/src/App.tsx](client/src/App.tsx)
2. Add route after line 70:
   ```tsx
   <Route path="/mobile/myapp" component={MobileMyApp} />
   ```
3. Create component in `client/src/pages/mobile-myapp.tsx`

### Task: Add API Endpoint

1. Edit [server/routes.ts](server/routes.ts)
2. Add inside `registerRoutes` function:
   ```ts
   app.post("/api/my-endpoint", requireAuth, async (req, res) => {
     // Your logic here
   });
   ```

---

## 📱 Mobile Integration: Full Guide

Want AeThex Studio on mobile? Let me create the mobile components for you!

The mobile UI currently has bottom navigation for:
- Home
- Desktop OS access
- Camera
- Modules

**We can add**:
- AeThex Studio (mobile code editor)
- App Store (mobile app browser)

**Would you like me to**:
1. Create mobile-specific Studio & Store components?
2. Add them to the mobile navigation?
3. Make them responsive/touch-optimized?

Let me know and I'll build it! 🚀

---

## Need Help?

- **All routes**: Check [client/src/App.tsx](client/src/App.tsx)
- **Desktop apps**: Check [client/src/pages/os.tsx](client/src/pages/os.tsx)
- **API endpoints**: Check [server/routes.ts](server/routes.ts)
- **Database schema**: Check [shared/schema.ts](shared/schema.ts)

**Start here**: http://localhost:5000/os — Opens the full desktop OS! 🖥️