Skip to main content

Coditect AI IDE - Quick Start Guide

🚀 One-Command Start​

# Start both services in background
./start-coditect.sh

# OR start in foreground (Ctrl+C stops both)
./start-coditect.sh --foreground

🛑 Stop Services​

./stop-coditect.sh

🌐 Access Points​

⭐ V5 Frontend (Main Application)​

URL: http://localhost:5173

This is the main entry point with:

  • Full Coditect UI: Header, Footer, Navigation
  • 28 Pages: Login, Settings, Documentation, Profile, FAQ, Support, etc.
  • workspace Tab: Embeds the theia IDE
  • AI Studio Tab: Loveable-style AI interface

Key Pages:

  • / - Home/Landing
  • /login - Authentication
  • /workspace - Main IDE (embeds theia)
  • /ai-studio - AI Studio interface
  • /settings - 8-section settings with TouchFriendlyCard
  • /documentation - Documentation hub with 18 sub-pages
  • /profile - User profile management

⚙️ theia IDE (Backend)​

URL: http://localhost:3000

Direct access to Eclipse theia with Coditect branding:

  • AI Chat: Custom "Coditect AI Agents" welcome message
  • Custom Logo: Coditect robot logo
  • Agent Instructions: @Coditect-Code-Generator, @Coditect-UI-Designer, etc.

🎨 Architecture​

┌─────────────────────────────────────────────────────────┐
│  V5 Frontend Wrapper (React + Vite)                     │
│  Port: 5173                                              │
│                                                           │
│  ┌─────────────┬──────────────┬─────────────────────┐  │
│  │  Header     │  Navigation  │  User Menu          │  │
│  ├─────────────┴──────────────┴─────────────────────┤  │
│  │                                                    │  │
│  │  ┌─────────────────────────────────────────────┐ │  │
│  │  │  workspace Tab (Main IDE)                   │ │  │
│  │  │  ┌─────────────────────────────────────┐   │ │  │
│  │  │  │  theia Iframe                        │   │ │  │
│  │  │  │  http://localhost:3000               │   │ │  │
│  │  │  │                                       │   │ │  │
│  │  │  │  ┌──────┬────────┬─────────────┐    │   │ │  │
│  │  │  │  │ File │ editor │  AI Chat    │    │   │ │  │
│  │  │  │  │ Tree │        │  (Branded)  │    │   │ │  │
│  │  │  │  └──────┴────────┴─────────────┘    │   │ │  │
│  │  │  └─────────────────────────────────────┘   │ │  │
│  │  └─────────────────────────────────────────────┘ │  │
│  │                                                    │  │
│  ├────────────────────────────────────────────────────┤  │
│  │  Footer: © 2025 Coditect AI                       │  │
│  └────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
            ┌───────────────────────────────┐
            │  theia Backend (Node.js)      │
            │  Port: 3000                   │
            │                               │
            │  - Eclipse theia 1.65         │
            │  - Coditect Branding          │
            │  - Custom AI Chat Welcome     │
            │  - Monaco editor              │
            │  - terminal (xterm.js)        │
            └───────────────────────────────┘

📦 Two-Service Architecture​

Service 1: theia Backend (Port 3000)​

  • Technology: Eclipse theia 1.65, Node.js, TypeScript
  • Purpose: IDE functionality, file operations, terminal, AI chat
  • Custom Branding: ChatWelcomeMessageProvider replaced with CoditectChatWelcomeMessageProvider
  • Startup: cd theia-app && npm start

Service 2: V5 Frontend Wrapper (Port 5173)​

  • Technology: React 18, TypeScript 5.3, Vite 5, Chakra UI 2.8
  • Purpose: Full application UI/UX, authentication, settings, documentation
  • Embeds: theia via iframe in workspace tab
  • Startup: npm run prototype:dev

🎯 Key Features​

V5 Frontend Features​

  • ✅ Apple-Quality Design System: Unified theme with 500+ design tokens
  • ✅ Mobile-First: Touch-friendly with 56px tap targets
  • ✅ 28 Complete Pages: Full application flow
  • ✅ 8-Section Settings: TouchFriendlyCard accordion UI
  • ✅ Documentation Hub: 18 sub-pages
  • ✅ Authentication: Login, Register, Password Reset
  • ✅ User Profile: Profile management and settings

theia Backend Features​

  • ✅ Custom AI Chat Branding: "Coditect AI Agents"
  • ✅ Custom Robot Logo: SVG-based Coditect branding
  • ✅ Agent Instructions: Custom @mention agents
  • ✅ Monaco editor: Full VS Code editor
  • ✅ terminal: xterm.js integration
  • ✅ File Explorer: theia Navigator

🔧 Manual Start (Alternative)​

If you prefer to start services manually:

terminal 1: theia Backend​

cd /workspace/PROJECTS/t2/theia-app
npm start
# Runs on http://localhost:3000

terminal 2: V5 Frontend​

cd /workspace/PROJECTS/t2
npm run prototype:dev
# Runs on http://localhost:5173

📝 Development Workflow​

Rebuild After Changes​

theia Changes (branding, extensions):

cd theia-app/src/browser
npx tsc                                      # Compile TypeScript
cd ../..
npx webpack --config gen-webpack.config.js  # Rebuild bundle
npm start                                    # Restart theia

V5 Frontend Changes (React components, pages):

# Vite has hot module replacement (HMR)
# Changes auto-reload in browser - no rebuild needed!

📊 Service Status​

Check if services are running:

# Check theia
curl http://localhost:3000 -I

# Check V5 Frontend
curl http://localhost:5173 -I

# Check ports
lsof -i:3000
lsof -i:5173

📝 Logs​

View real-time logs:

# theia logs
tail -f /tmp/theia.log

# V5 Frontend logs
tail -f /tmp/vite.log

🐛 Troubleshooting​

Port Already in Use​

# Kill existing processes
lsof -ti:3000 | xargs kill -9
lsof -ti:5173 | xargs kill -9

theia Not Loading​

# Check if webpack bundle exists
ls -la theia-app/lib/frontend/bundle.js

# Rebuild if needed
cd theia-app
npx webpack --config gen-webpack.config.js

V5 Frontend Build Errors​

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Branding Not Showing​

  1. Check browser console (F12) for errors
  2. Verify module loading: grep "Coditect branding" /tmp/theia.log
  3. Hard refresh browser (Ctrl+Shift+R)
  4. Rebuild theia bundle if source changed

🎉 Success Verification​

✅ Both Services Running:

✅ Branding Working:

  • Open http://localhost:3000
  • View → AI Chat
  • See "Coditect AI Agents" (not "Ask the theia IDE AI")
  • See custom robot logo

✅ V5 Wrapper Working:

  • Open http://localhost:5173
  • Navigate to workspace tab
  • theia iframe loads inside V5 UI
  • Header and footer display

📚 Documentation​

  • Full Solution: theia-app/coditect-branding-solution.md
  • Architecture: docs/DEFINITIVE-V5-architecture.md
  • Design System: docs/apple-quality-design-system.md
  • Build Status: docs/v5-frontend-build-verification.md

Last Updated: 2025-10-08 Status: ✅ Both services working theia Version: 1.65.0 React Version: 18.3.1 Vite Version: 5.4.20