Orbit — AI-Powered Project Controller

Table of Contents

• The Challenge
• Architecture & Solution
• Tech Stack
• Key Engineering Decisions
• AI Diagnostics Engine
• Pipeline System
• Deployment
• Roadmap

The Challenge

Managing a multi-project development environment across multiple VPS nodes introduces a fragmentation problem that grows exponentially with scale. The reality of a modern full-stack developer's workflow looks like this:

• Terminal tab sprawl: One tab for each project dev server, one for logs, one for Docker, one for SSH — easily 10+ tabs open simultaneously
• No centralized visibility: Each project has its own lifecycle (dev server, build process, Docker Compose) with no unified dashboard to monitor all of them
• Manual deployment workflows: Deploying to VPS requires SSH-ing in, pulling code, rebuilding containers — a multi-step dance prone to human error
• Debugging in silos: When a project crashes, developers switch context to read raw logs in isolated terminals, losing system-wide perspective
• No AI assistance: Runtime errors require manual investigation — no integrated assistant to analyze logs and suggest fixes

The requirement: Build a single terminal command-center that discovers all local projects, manages their complete lifecycles, monitors remote VPS infrastructure, and provides AI-powered debugging — all through a keyboard-driven interface that feels as fast as Vim.

Architecture & Solution

Orbit is a dual-layer architecture combining a React/Ink TUI frontend with a Go-based AI engine for complex LLM interactions and tool execution.

Component Responsibilities

Tech Stack

Key Engineering Decisions

1. React/Ink over Bubbletea (Go)

Orbit's TUI is built with React + Ink rather than a Go-based framework like Bubble Tea or Charm's Tea. The decision came down to:

• React ecosystem: Reusable components (<Box>, <Text>, <Spacer>) with a familiar paradigm
• State management: React hooks (useState, useEffect, useCallback) map cleanly to TUI state
• Component reuse: UI components like ProjectList, LogViewer, Modal share logic across views

Go's bubble tea would have been faster for I/O but would have required rewriting all UI components from scratch.

2. Real-Time Polling over Event-Driven Architecture

Orbit uses setInterval polling every 5 seconds to check:

• Project port binding (lsof on localhost)
• Remote Docker container counts (SSH to each VPS node)
• Log stream updates

// Polling interval in src/core/polling.ts
const POLL_INTERVAL = 5000; // 5 seconds

setInterval(async () => {
  const runningPorts = await getBoundPorts();
  updateProjectStatus(projects, runningPorts);
  
  for (const node of VPS_NODES) {
    const containerCount = await sshDockerPs(node.host);
    updateNodeHealth(node.id, containerCount);
  }
}, POLL_INTERVAL);

While event-driven would be more efficient, polling proved simpler to implement and sufficient for the 3-node deployment scale. The plan.md file explicitly notes this as a pain point to address in future versions with a pub/sub event system.

3. Pipeline Fallback — Dual-Mode Execution

Orbit's pipeline system supports two execution modes:

1. Native Mode (preferred): When orbit.yml exists, Orbit parses the YAML and executes each task natively with rich UI tracking (spinners, progress indicators)
2. Legacy Fallback: When no orbit.yml exists, Orbit executes the project's existing deploy.sh or start.sh script unchanged

# orbit.yml example
name: aatmanova-deploy
tasks:
  - name: Build Docker Image
    type: local_exec
    command: docker build -t aatmanova:latest .
  
  - name: SSH to Production
    type: ssh_exec
    host: node-2
    command: docker pull aatmanova:latest
  
  - name: Health Check
    type: http_health_check
    url: https://aatmanova.school/health
    timeout: 30

This dual-mode approach means zero migration required — existing projects work immediately while new projects can opt into the native pipeline with richer UI.

4. Port Conflict Zero (PCZ) System

Orbit acts as a deterministic port manager. Instead of relying on OS-assigned ports that clash when running multiple projects:

// PCZ — hash-based port assignment
const PORT_BLOCK_SIZE = 50;
const getProjectPort = (projectName: string, offset: number): number => {
  const hash = stringHash(projectName);
  const basePort = 3000 + (hash % 10) * PORT_BLOCK_SIZE;
  return basePort + offset;
};

When a user presses s to start a dev server, Orbit injects PORT_WEB, PORT_API environment variables from this deterministic block — guaranteeing no port conflicts across the 4+ managed projects.

5. Keyboard-First Navigation

Every interaction works without leaving the home row:

AI Diagnostics Engine

Orbit integrates a custom Go-based AI engine (located in source-code/) that handles:

LLM Interaction

• Connects to Gemini or OpenAI APIs
• Sends recent log context + project metadata
• Receives structured fix suggestions

Error Pattern Recognition

// src/core/ai.ts — pattern-based suggestions
if (errorLog.includes('EADDRINUSE')) {
  return "💡 Suggestion: The port is already in use. Run `npx kill-port <port>` or use Orbit's [x] key to stop the previous instance.";
}

if (errorLog.includes('Cannot find module')) {
  return "💡 Suggestion: Missing dependencies. Try running `npm install` or `pnpm install` in the project directory.";
}

Tool Execution

The Go-Based AI Engine can execute real shell commands suggested by the LLM, not just return text — it can actually run npm install, restart processes, or modify files based on AI recommendations.

Pipeline System

The orbit.yml pipeline system supports four task types:

When executing, the PipelineTracker modal shows:

• Spinner for running (⠋)
• Success for completed (✓)
• Error for failed (✖)
• Real-time stderr/stdout capture

Deployment

Quick Start

# From anywhere on the system (after npm link)
orbit

# Or from project directory
cd /home/bhargavxharma/DATABASE/localhost/01_codes/orbit
pnpm run start

Service Topology

Production VPS Nodes

Production Checklist

# Install dependencies
pnpm install

# Link CLI globally
npm link

# Verify project discovery
orbit  # Should auto-detect projects in /home/bhargavxharma/DATABASE/localhost/01_codes

# Test AI diagnostics
export GEMINI_API_KEY="your-key"
# Press 'a' on any project with error logs

# Test pipeline execution
# Create orbit.yml in target project, then press 'd' to deploy

Roadmap

Phase 1 — Project Discovery & Basic Lifecycle (Complete)

• Auto-scan workspace directories
• Start/stop dev servers, build projects

Phase 2 — Multi-View & Server Health (Complete)

• 5 views: Projects, Servers, Logs, Chat, Cluster
• Live SSH polling for Docker container counts

Phase 3 — AI Diagnostics & Env Manager (Complete)

• Gemini API log analysis
• Local .env reading and display

Phase 4 — Dual-Mode Pipeline Engine (Complete)

• Native orbit.yml parsing with rich UI
• Legacy deploy.sh fallback

Phase 5 — Advanced Operations (Complete)

• Real-time log streaming (L key)
• Environment diff viewer (V key)

Phase 6 — Ecosystem Standardization (Complete)

• Port Conflict Zero (PCZ) system
• Custom tasks in orbit.yml
• Orbit-ify engine for project templating

Phase 7 — Event-Driven Architecture (In Progress)

• Replace polling with pub/sub event system
• Implement theme tokens (dark/light mode)

Phase 8 — Plugin System (Planned)

• Third-party tool integrations
• Custom command registration

Phase 9 — Multi-User Mode (Future)

• Team collaboration via shared SSH keys
• Role-based access control