aethex-studio/IMPLEMENTATION_ROADMAP.md

# 🚀 AeThex Studio: Strategic Implementation Roadmap

## Vision → Reality Transformation Plan

This document outlines the **concrete, actionable steps** to transform AeThex Studio from a Roblox-only IDE into a **multi-platform game development powerhouse** with cross-platform translation as the core competitive differentiator.

---

## ✅ PHASE 1: FOUNDATION (COMPLETED)

### What We Built

#### 1. **Platform Abstraction Layer** (`src/lib/platforms.ts`)
- **Purpose**: Central configuration for all supported platforms
- **Platforms Defined**:
  - ✅ Roblox (Lua 5.1) - ACTIVE
  - ✅ UEFN (Verse) - BETA
  - 🔜 Spatial (TypeScript) - COMING SOON
  - 🔜 Core (Lua 5.3) - COMING SOON

**Code Structure**:
```typescript
interface Platform {
  id: PlatformId;
  name: string;
  displayName: string;
  language: string;
  fileExtension: string;
  description: string;
  color: string;
  icon: string;
  apiDocs: string;
  status: 'active' | 'beta' | 'coming-soon';
}
```

#### 2. **Cross-Platform Translation Engine** (`src/lib/translation-engine.ts`)
- **Core Differentiator**: AI-powered code translation between platforms
- **Current State**: Mock implementation (ready for Claude API integration)
- **Features**:
  - Platform-specific translation prompts
  - Translation validation
  - Error handling and analytics
  - Support for 6 translation pairs (Roblox ↔ UEFN ↔ Spatial)

**Translation Flow**:
```
User Code (Roblox Lua)
  → Translation Engine
  → Claude API (with platform-specific prompts)
  → Translated Code (UEFN Verse)
  → Side-by-side comparison
```

#### 3. **UI Components**

**PlatformSelector** (`src/components/PlatformSelector.tsx`):
- Dropdown to switch between platforms
- Shows platform icon, name, language
- Displays BETA/Coming Soon badges
- Integrated into toolbar

**TranslationPanel** (`src/components/TranslationPanel.tsx`):
- Full-screen modal with side-by-side code view
- Source platform (current) vs Target platform (selected)
- Real-time translation with loading states
- Copy translated code button
- Explanation and warnings section

#### 4. **Template System Update** (`src/lib/templates.ts`)
- Added `platform: PlatformId` field to all 25 templates
- All templates marked as `platform: 'roblox'`
- New function: `getTemplatesForPlatform(platform: PlatformId)`
- Ready for UEFN, Spatial, Core templates

---

## 🔧 PHASE 2: INTEGRATION (IN PROGRESS)

### What Needs to Be Done

#### 1. **App.tsx State Management**

Add platform state to main application:

```typescript
// Add to App.tsx state
const [currentPlatform, setCurrentPlatform] = useState<PlatformId>('roblox');
const [showTranslationPanel, setShowTranslationPanel] = useState(false);

// Update Toolbar integration
<Toolbar
  code={currentCode}
  currentPlatform={currentPlatform}
  onPlatformChange={setCurrentPlatform}
  onTranslateClick={() => setShowTranslationPanel(true)}
  onTemplatesClick={() => setShowTemplates(true)}
  onPreviewClick={() => setShowPreview(true)}
  onNewProjectClick={() => setShowNewProject(true)}
/>

// Add TranslationPanel
<TranslationPanel
  isOpen={showTranslationPanel}
  onClose={() => setShowTranslationPanel(false)}
  currentCode={currentCode}
  currentPlatform={currentPlatform}
/>
```

#### 2. **Template Filtering**

Update TemplatesDrawer to filter by platform:

```typescript
import { getTemplatesForPlatform } from '@/lib/templates';

// Inside TemplatesDrawer component
const platformTemplates = getTemplatesForPlatform(currentPlatform);

// Group by category and render
const categories = {
  beginner: platformTemplates.filter(t => t.category === 'beginner'),
  // ... etc
};
```

#### 3. **File Extension Handling**

Update file creation to use platform-specific extensions:

```typescript
import { getFileExtensionForPlatform } from '@/lib/platforms';

const handleFileCreate = (name: string, parentId?: string) => {
  const extension = getFileExtensionForPlatform(currentPlatform);
  const fileName = name.endsWith(extension) ? name : `${name}${extension}`;

  const newFile: FileNode = {
    id: `file-${Date.now()}`,
    name: fileName,
    type: 'file',
    content: `-- New ${currentPlatform} file\n`,
  };
  // ... rest of file creation logic
};
```

#### 4. **Monaco Editor Language**

Update CodeEditor to set correct language based on platform:

```typescript
const languageMap: Record<PlatformId, string> = {
  roblox: 'lua',
  uefn: 'plaintext', // Verse not yet supported by Monaco
  spatial: 'typescript',
  core: 'lua',
};

<Editor
  height="100%"
  defaultLanguage={languageMap[currentPlatform]}
  // ... rest of editor props
/>
```

---

## 🎯 PHASE 3: UEFN EXPANSION (NEXT PRIORITY)

### Create UEFN Template Library

#### First 5 UEFN Templates to Create:

**1. Hello World (Verse)**
```verse
using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }

hello_world := class(creative_device):
    OnBegin<override>()<suspends>:void=
        Print("Hello from UEFN!")
```

**2. Player Join Handler**
```verse
using { /Fortnite.com/Game }
using { /Fortnite.com/Characters }

player_tracker := class(creative_device):
    OnBegin<override>()<suspends>:void=
        GetPlayspace().PlayerAddedEvent().Subscribe(OnPlayerAdded)

    OnPlayerAdded(Player:player):void=
        Print("Player joined: {Player}")
```

**3. Button Interaction**
```verse
using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }

button_handler := class(creative_device):
    @editable
    MyButton : button_device = button_device{}

    OnBegin<override>()<suspends>:void=
        MyButton.InteractedWithEvent.Subscribe(OnButtonPressed)

    OnButtonPressed(Agent:agent):void=
        Print("Button pressed!")
```

**4. Timer Countdown**
**5. Score Tracker**

Create file: `src/lib/templates-uefn.ts` with these templates.

---

## 🤖 PHASE 4: CLAUDE API INTEGRATION

### Replace Mock Translation with Real AI

#### 1. Environment Setup

Add to `.env.local`:
```bash
CLAUDE_API_KEY=sk-ant-api03-...
CLAUDE_MODEL=claude-3-5-sonnet-20241022
```

#### 2. Update `translation-engine.ts`

Replace `translateWithClaudeAPI` function:

```typescript
async function translateWithClaudeAPI(
  request: TranslationRequest
): Promise<TranslationResult> {
  const apiKey = process.env.NEXT_PUBLIC_CLAUDE_API_KEY;

  if (!apiKey) {
    return {
      success: false,
      error: 'Claude API key not configured',
    };
  }

  const prompt = getTranslationPrompt(
    request.sourceCode,
    request.sourcePlatform,
    request.targetPlatform,
    request.context
  );

  try {
    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey,
        'anthropic-version': '2023-06-01',
      },
      body: JSON.stringify({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 4096,
        messages: [
          {
            role: 'user',
            content: prompt,
          },
        ],
      }),
    });

    if (!response.ok) {
      throw new Error(`API request failed: ${response.statusText}`);
    }

    const data = await response.json();
    const content = data.content[0].text;

    // Parse code blocks and explanation
    const codeMatch = content.match(/```[\w]+\n([\s\S]*?)```/);
    const explanationMatch = content.match(/\*\*Explanation\*\*:\s*(.*?)(?:\n\*\*|$)/s);
    const warningsMatch = content.match(/\*\*Warnings\*\*:\s*([\s\S]*?)(?:\n\*\*|$)/);

    return {
      success: true,
      translatedCode: codeMatch ? codeMatch[1].trim() : content,
      explanation: explanationMatch ? explanationMatch[1].trim() : undefined,
      warnings: warningsMatch
        ? warningsMatch[1].split('\n').filter(w => w.trim())
        : undefined,
    };
  } catch (error) {
    captureError(error as Error, {
      context: 'claude_api_translation',
      sourcePlatform: request.sourcePlatform,
      targetPlatform: request.targetPlatform,
    });

    return {
      success: false,
      error: `Translation failed: ${(error as Error).message}`,
    };
  }
}
```

---

## 📊 PHASE 5: MONETIZATION

### Authentication & Payment Integration

#### 1. Add Clerk Authentication

```bash
npm install @clerk/nextjs
```

Create `app/providers.tsx`:
```typescript
import { ClerkProvider } from '@clerk/nextjs';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ClerkProvider>{children}</ClerkProvider>;
}
```

#### 2. Feature Flags by Tier

Create `src/lib/feature-flags.ts`:
```typescript
export type SubscriptionTier = 'free' | 'studio' | 'pro' | 'enterprise';

export interface FeatureAccess {
  maxTemplates: number;
  translation: boolean;
  desktopApp: boolean;
  teamCollaboration: boolean;
  advancedAnalytics: boolean;
  prioritySupport: boolean;
}

export const tierFeatures: Record<SubscriptionTier, FeatureAccess> = {
  free: {
    maxTemplates: 5,
    translation: false,
    desktopApp: false,
    teamCollaboration: false,
    advancedAnalytics: false,
    prioritySupport: false,
  },
  studio: {
    maxTemplates: 25,
    translation: false,
    desktopApp: true,
    teamCollaboration: false,
    advancedAnalytics: false,
    prioritySupport: true,
  },
  pro: {
    maxTemplates: -1, // unlimited
    translation: true, // 🔥 CORE DIFFERENTIATOR
    desktopApp: true,
    teamCollaboration: true,
    advancedAnalytics: true,
    prioritySupport: true,
  },
  enterprise: {
    maxTemplates: -1,
    translation: true,
    desktopApp: true,
    teamCollaboration: true,
    advancedAnalytics: true,
    prioritySupport: true,
  },
};
```

#### 3. Stripe Integration

```bash
npm install @stripe/stripe-js stripe
```

Create pricing page with tiers:
- **Foundation (Free)**: Roblox only, 5 templates
- **Studio ($15/mo)**: Desktop app, all Roblox templates
- **Pro ($45/mo)**: 🔥 **Translation engine**, all platforms, team features
- **Enterprise (Custom)**: SSO, dedicated support, custom deployment

---

## 🏢 PHASE 6: COLLABORATION & EDUCATION

### Real-Time Collaboration

#### 1. Add Yjs for CRDT

```bash
npm install yjs y-websocket
```

#### 2. WebSocket Server Setup

Create `server/websocket.ts`:
```typescript
import { WebSocketServer } from 'ws';
import * as Y from 'yjs';

const wss = new WebSocketServer({ port: 1234 });

const docs = new Map<string, Y.Doc>();

wss.on('connection', (ws, req) => {
  const roomId = new URL(req.url!, 'http://localhost').searchParams.get('room');

  if (!roomId) {
    ws.close();
    return;
  }

  const doc = docs.get(roomId) || new Y.Doc();
  docs.set(roomId, doc);

  // Sync document state
  // Handle updates
  // Broadcast to all clients in room
});
```

### Teacher Dashboard Implementation

Activate existing `TeacherDashboard.tsx` component:
- Student management (add, remove, view progress)
- Assignment creation with due dates
- Code submission review interface
- Grade tracking and analytics

---

## 🎮 PHASE 7: PLATFORM EXPANSION

### Q3-Q4 2024: Spatial Support

1. Create `src/lib/templates-spatial.ts` with 25 TypeScript templates
2. Update translation prompts for Lua/Verse → TypeScript
3. Add Spatial Creator Toolkit documentation links
4. Test translation accuracy

### Year 2: Core Games Support

1. Create `src/lib/templates-core.ts` with 25 Lua templates
2. Map Roblox APIs to Core APIs in translation prompts
3. Add Core documentation integration

---

## 📈 SUCCESS METRICS

### Phase 2 (Integration) - 1 Week
- [ ] Platform switching works in UI
- [ ] Templates filter by platform
- [ ] Translation panel opens and displays mock translation
- [ ] File extensions change based on platform

### Phase 3 (UEFN) - 2 Weeks
- [ ] 5 UEFN templates created
- [ ] Roblox → UEFN translation tested manually
- [ ] Platform switcher shows Roblox + UEFN

### Phase 4 (Claude API) - 1 Week
- [ ] Claude API key configured
- [ ] Real translation working for simple scripts
- [ ] Translation accuracy >70% for basic examples
- [ ] Error handling for API failures

### Phase 5 (Monetization) - 3-4 Weeks
- [ ] Clerk auth integrated
- [ ] Free tier limits enforced (5 templates)
- [ ] Pro tier unlocks translation
- [ ] Stripe checkout working
- [ ] First paying customer

### Phase 6 (Collaboration) - 6-8 Weeks
- [ ] Real-time editing works for 2+ users
- [ ] Teacher dashboard MVP launched
- [ ] Assignment submission system working
- [ ] First classroom using platform

---

## 🎯 COMPETITIVE POSITIONING

### vs Superbullet.ai

| Feature | Superbullet.ai | AeThex Studio (After Phase 4) |
|---------|---------------|-------------------------------|
| Platforms | ❌ Roblox only | ✅ Roblox + UEFN + Spatial + Core |
| Translation | ❌ No | ✅ **Cross-platform AI translation** |
| Desktop App | ❌ No | ✅ Yes (Electron) |
| Collaboration | ❌ No | ✅ Real-time editing |
| Education | ❌ No | ✅ Teacher dashboard |
| Pricing | $19.90/mo | $45/mo (Pro with translation) |

**Value Proposition**:
> "Build your game once in Roblox Lua, translate to UEFN Verse, Spatial TypeScript, and Core Lua with one click. The only IDE that lets you deploy to every major game platform."

---

## 🚨 CRITICAL NEXT STEPS (This Week)

### Priority 1: Complete Phase 2 Integration
1. Update `App.tsx` with platform state (30 minutes)
2. Pass props to Toolbar and TemplatesDrawer (15 minutes)
3. Test platform switching (15 minutes)
4. Test translation panel UI (mock translation) (30 minutes)

### Priority 2: Create First UEFN Template
1. Research Verse syntax for hello world (1 hour)
2. Create `templates-uefn.ts` with 1 template (30 minutes)
3. Test loading UEFN template in editor (15 minutes)

### Priority 3: Claude API Integration
1. Get Claude API key (5 minutes)
2. Update `.env.local` (2 minutes)
3. Implement real `translateWithClaudeAPI` (2 hours)
4. Test simple Roblox → UEFN translation (1 hour)

**Total Time to MVP Translation**: ~6-8 hours

---

## 💡 QUICK WINS

These can be done in <1 hour each for immediate impact:

1. **Update README.md** with "Multi-Platform Support" section
2. **Add platform badges** to templates drawer
3. **Create demo video** showing Roblox → UEFN translation
4. **Add "Coming Soon" banner** for Spatial and Core
5. **Analytics event** tracking for platform switches and translations

---

## 📞 NEXT ACTIONS

**What do you want to tackle first?**

A. **Complete Phase 2 integration** (App.tsx, test platform switching)
B. **Create UEFN templates** (5 Verse examples)
C. **Claude API integration** (make translation real)
D. **Create demo/marketing content** (show off the differentiator)
E. **Something else?** (tell me what)

I'm ready to implement whichever you choose. Let's make this real! 🚀