Add repository restructuring plan and module architecture

[Copilot]

Establishes foundation for restructuring Skyscale to support both Lambda-style execution and E2B-style long-lived sandboxes through clean architectural boundaries.

Architecture

Introduces module-first organization:

vm/          # Firecracker isolation - nothing else touches it directly
runtime/     # Guest agent + protocol contracts
sandbox/     # Long-lived sessions via same VM infrastructure
sdk/         # Client libraries (Lambda + Sandbox styles)
internal/    # Shared utilities

Key principle: Separation by responsibility, not language. VM operations stay in vm/, enabling Lambda, sandboxes, and REPLs to share infrastructure with different policies.

Deliverables

Documentation

• RESTRUCTURING.md - Architecture rationale and migration strategy
• MILESTONES.md - 9 milestones, 4-month timeline
• ISSUES.md - 66 issues with acceptance criteria
• docs/architecture.md - System design and data flows

Structure

• 25 module directories with README files documenting:
  • Module responsibilities and boundaries
  • Migration path from existing code
  • Future API surface
  • Related tracking issues

Migration Approach

Low-risk incremental extraction:

1. VM logic → vm/ (Issues #5-12)
2. Guest runtime → runtime/ (Issues #13-19)
3. Control plane cleanup (Issues #20-26)
4. Sandbox implementation behind feature flag (Issues #27-35)

No functional changes in this PR - existing code builds and runs unchanged.

What This Enables

Near-term: E2B-style persistent sandboxes without touching Lambda code paths

Long-term: Programmable compute substrate for notebooks, CI/CD sandboxes, ML training, dev environments

Original prompt

Create issues in this repo and also add milestones for completion - Got it — you already have real infrastructure, not a toy.
So this is not a “rewrite”, it’s a structural hardening to support:

• Lambda-style execution and
• E2B-style long-lived sandboxes
• Snapshot-based fast paths
• Cleaner ownership boundaries

Below is a repo restructuring proposal that keeps your work intact and prepares Skyscale for a Sandbox API without architectural debt.

---

Core Design Principle

Separate by responsibility, not by language or feature.

Right now, concepts are slightly interleaved:

• “Function execution”
• “VM lifecycle”
• “Control-plane logic”
• “Guest runtime”

Those must become first-class modules.

---

Proposed Top-Level Structure

skyscale/
│
├── cmd/                     # Entry points only (thin)
│   ├── control-plane/
│   ├── sandboxd/             # NEW: sandbox-oriented daemon
│   └── cli/
│
├── control-plane/            # API + orchestration logic
│   ├── api/
│   ├── scheduler/
│   ├── auth/
│   ├── state/
│   └── registry/
│
├── vm/                       # Firecracker & VM lifecycle (CRITICAL)
│   ├── manager/
│   ├── pool/
│   ├── snapshot/
│   ├── network/
│   └── jailer/
│
├── runtime/                  # Guest-side logic (inside VM)
│   ├── agent/                # Go agent (current)
│   ├── python/
│   └── protocol/
│
├── sandbox/                  # NEW: E2B-style abstraction
│   ├── api/
│   ├── lifecycle/
│   ├── exec/
│   └── fs/
│
├── sdk/                      # Client-facing SDKs
│   ├── python/
│   └── types/
│
├── assets/
│   ├── kernels/
│   ├── rootfs/
│   └── snapshots/
│
├── internal/                 # Shared internal utilities
│   ├── logging/
│   ├── config/
│   └── errors/
│
├── perf/
├── scripts/
├── examples/
└── docs/

---

Why This Structure Works

1. vm/ becomes sacred ground

Everything Firecracker-related lives here.

vm/
├── manager/      # start/stop microVMs
├── pool/         # pre-warmed VM pools
├── snapshot/     # create / restore snapshots
├── network/      # tap, vsock, bridges
└── jailer/       # seccomp, UID isolation

Rule:
Nothing outside vm/ talks to Firecracker directly.

This is what allows:

• Lambda execution
• Sandboxes
• REPLs
• Tests
  to all reuse the same VM machinery.

---

2. runtime/ cleanly separates host vs guest

You already have a Go agent — formalize it.

runtime/
├── agent/        # runs INSIDE VM
├── python/       # bootstrap + handler runner
└── protocol/     # host ↔ guest contracts

Protocol is key

Define:

• Exec
• UploadFile
• StreamLogs
• Shutdown

Once frozen, everything becomes composable.

---

3. sandbox/ is a new first-class product

This is how you add E2B-style sandboxes without touching Lambda logic.

sandbox/
├── api/          # /sandboxes/*
├── lifecycle/    # create, suspend, resume, destroy
├── exec/         # shell + python execution
└── fs/           # workspace, mounts, limits

Important:
A sandbox is just:

a long-lived VM + relaxed execution semantics

Same VM manager. Different policy.

---

4. control-plane/ stops doing too much

It becomes orchestration-only.

control-plane/
├── api/          # REST / gRPC
├── scheduler/    # routing decisions
├── auth/
├── state/
└── registry/

No Firecracker code here.
No runtime logic here.

---

5. cmd/ stays thin (this is non-negotiable)

cmd/control-plane/main.go
cmd/sandboxd/main.go
cmd/cli/main.go

Each one:

• Loads config
• Wires dependencies
• Starts services

No business logic.

---

6. SDKs live outside infra

sdk/python/

This will eventually support:

# Lambda-style
invoke("fn", payload)

# Sandbox-style
sb = Sandbox()
sb.exec("pip install torch")
sb.exec("python train.py")

Same backend. Different UX.

---

Migration Strategy (Low Risk)

Step 1 – Extract VM logic

Move Firecracker code → vm/

No behavior change.

Step 2 – Formalize guest protocol

Lock host ↔ agent contracts.

Step 3 – Introduce sandbox/ behind feature flag

Reuse:

• VM pool
• Snapshots
• Agent

Step 4 – SDK-first development

Design Python SDK before API changes.

---

What This Unlocks

Immediately:

• REPL-like sandboxes
• Stateful execution
• Better cold-start control

Soon:

• Notebook-style workflows
• CI sandboxes
• ML training jobs
• Dev environments

Long-term:

• Skyscale ≠ Lambda clone
• Skyscale = programmable compute substrate

That’s the right direction.

---

If you want next-level depth

I can next:

1. Define the host ↔ agent protocol
2. Design the snapshot layering model
3. Draft the sandbox REST + SDK API
4. Propose exact package boundaries in Go

Tell me which one to go deep on.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.