🚀 MVP Architecture

Minimal viable fleet: Railway for agents only, everything else static/free.

Cost Analysis

Original Design

Dashboard (Vercel Pro)	$20
API Worker (Cloudflare)	$5+
Database (Supabase Pro)	$25
Agents (Railway, 10×)	$50-100
Total	$100-150/mo

MVP Design

Setup Wizard (GitHub Pages)	FREE
Dashboard (GitHub Pages)	FREE
Fleet Config (JSON in repo)	FREE
Agents (Railway, 10×)	$50-100
Total	$50-100/mo

50%+ Savings — by eliminating Supabase/Vercel/Workers

Architecture

flowchart TB
  subgraph GP["🆓 GitHub Pages (FREE) · menonpg.github.io/neo-agent"]
    direction LR
    WZ["/wizard/
onboarding form"]
    DB["/dashboard/
fleet status"]
    DC["/docs/
setup guides"]
  end
  subgraph REPO["🆓 GitHub Repo (FREE) · menonpg/neo-fleet (private)"]
    direction LR
    FJ["fleet.json
registry"]
    CU["customers/
configs"]
    WF[".github/workflows/
automation"]
  end
  subgraph RW["💳 Railway (pay per agent · ~$5-10/mo each)"]
    direction LR
    R1["neo-lw-auto"]
    R2["neo-anasto-1"]
    R3["neo-internal"]
  end
  GP -- "customer submits form" --> REPO
  REPO -- "GitHub Action spawns" --> RW

┌─────────────────────────────────────────────────────────────────┐
│  GITHUB PAGES (FREE)                                             │
│  menonpg.github.io/neo-agent/                                   │
│                                                                  │
│  ├── /wizard/     → Customer onboarding form                    │
│  ├── /dashboard/  → Fleet status viewer (static)                │
│  └── /docs/       → Setup guides                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Customer submits form
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  GITHUB REPO (FREE)                                              │
│  menonpg/neo-fleet (private)                                    │
│                                                                  │
│  ├── fleet.json         → Agent registry                        │
│  ├── customers/         → Customer configs                      │
│  └── .github/workflows/ → Automation                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ GitHub Action spawns
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  RAILWAY (PAY PER AGENT)                                         │
│                                                                  │
│  ├── neo-lw-auto        → LW Automotive agent                   │
│  ├── neo-anasto-1       → Anasto customer agent                 │
│  └── neo-internal       → Our internal agent                    │
│                                                                  │
│  Each ~$5-10/mo depending on usage                              │
└─────────────────────────────────────────────────────────────────┘

How It Works

1. Customer Onboarding

Options: GitHub Issue template or Google Form → manual review → spawn.

# .github/ISSUE_TEMPLATE/new-agent.yml
name: Request New Agent
body:
  - type: input
    id: company
    attributes:
      label: Company Name
    validations:
      required: true
      
  - type: dropdown
    id: provider
    attributes:
      label: AI Provider
      options:
        - GitHub Copilot
        - OpenAI
        - Anthropic

2. Fleet Registry

Simple JSON file in repo tracks all agents.

{
  "agents": [
    {
      "id": "neo-lw-auto",
      "customer": "LW Automotive",
      "railway_service_id": "srv_xxx",
      "status": "running",
      "provider": "github-copilot",
      "channel": "telegram",
      "domain": "automotive",
      "created_at": "2026-06-28"
    }
  ]
}

3. Static Dashboard

GitHub Pages fetches fleet.json and renders status cards.

async function loadFleet() {
  const res = await fetch(
    'https://raw.githubusercontent.com/menonpg/neo-fleet/main/fleet.json'
  );
  const data = await res.json();
  
  container.innerHTML = data.agents.map(agent => `
    <div class="card">
      <h3>${agent.id}</h3>
      <span class="${agent.status}">${agent.status}</span>
      <p>${agent.customer}</p>
    </div>
  `).join('');
}

4. Spawn via GitHub Action

Workflow dispatch creates Railway service and updates registry.

# .github/workflows/spawn-agent.yml
name: Spawn Agent
on:
  workflow_dispatch:
    inputs:
      agent_id:
        description: 'Agent ID (e.g., neo-customer-1)'
        required: true
      provider:
        type: choice
        options: [github-copilot, openai, anthropic]

jobs:
  spawn:
    runs-on: ubuntu-latest
    steps:
      - name: Create Railway Service
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
        run: |
          # Create service via Railway API
          # Inject secrets, deploy, update fleet.json

5. Health Check Cron

Every 30 min, check each agent and update status.

# .github/workflows/health-check.yml
on:
  schedule:
    - cron: '*/30 * * * *'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check Agent Health
        run: |
          for agent in $(jq -r '.agents[].railway_url' fleet.json); do
            curl -sf "$agent/health" && STATUS="running" || STATUS="unhealthy"
            # Update fleet.json
          done

Secret Handling

Without a backend, secrets are handled manually:

Option 1: Railway Dashboard

Customer provides token via secure channel. We add to Railway env vars manually.

Option 2: Railway CLI in Action

Token passed as workflow input, set via API, never stored in git.

Option 3: GitHub Secrets

Per-customer secrets: CUSTOMER_LW_TOKEN. Referenced in spawn workflow.

MVP Limitations

Feature	Full Version	MVP
Onboarding	Automated wizard	GitHub Issue / Form
Secret entry	Web form + validate	Manual via secure channel
Dashboard	Live updates	Refresh to see changes
Billing	Stripe integration	Manual invoicing
Health alerts	Slack/email	Check dashboard

Cost Summary

Just us (1-2 internal agents)	$10-20/mo
+ 5 customer agents	$35-70/mo
+ 10 customer agents	$60-120/mo

All infrastructure (wizard, dashboard, registry) = FREE via GitHub

"Ship the MVP. Add complexity when revenue justifies it."

← Back to Neo