docs(requirements): Kubernetes-friendly architecture plan

[Yambr]

Summary

Adds a forward-looking design folder under docs/requirements/ that describes the target Kubernetes-friendly architecture and the phased delivery plan. No code changes. The Docker Compose path is unaffected.

The intent is to fix the direction in writing before any implementation PR lands, so contributors and integrators can review the architecture as a whole rather than inferring it from a series of incremental diffs.

What's in this PR

• docs/requirements/README.md — framing for the new folder: it holds plans, not user docs; the running system always wins over a draft if they conflict.
• docs/requirements/k8s-architecture.md — target architecture:
  • RuntimeBackend abstraction over Docker and Kubernetes
  • Four-tier storage model: base image / squashfs skill blobs / workspace home (RWO or ephemeral) / object-store-backed user data with chat-scoped key prefix
  • Warm pool for sub-second time-to-ready on Kubernetes
  • Optional VM-class isolation tier (kata-fc) selectable per workspace
  • Vendor-neutral S3 (works against AWS S3, MinIO, R2, Ceph RGW, …)
• docs/requirements/roadmap.md — six-phase plan, each phase ships independently; Phase 1 is a pure refactor; Compose users keep working through every phase.
• README.md — one-line pointer so contributors can discover the folder from the project entry point.

Why now

The project today runs on Docker Compose with bind-mounted host paths for skills and user data. Several of those choices do not translate cleanly to a multi-node Kubernetes deployment (no RWX storage, host bind incompatibility, single-node assumptions in cron/). Writing the plan down up front makes the eventual code PRs small and reviewable, and gives operators a clear signal about where the project is heading.

Non-goals

• No build of a custom file-store service.
• No custom guest agent — the existing entrypoint plus MCP server stays.
• No L7 egress filter; NetworkPolicy is sufficient for the initial work.
• No live migration of running workspaces.

What stays compatible

• docker compose up continues to work in every phase.
• The MCP tool surface is untouched.
• The Open WebUI integration is unchanged.
• The workspace Dockerfile is unchanged; both backends pull the same image.

Test plan

• Render docs/requirements/*.md on GitHub and confirm cross-links resolve.
• Confirm the README pointer appears under the Architecture section.
• No code paths exercised — tests/ unaffected.

https://claude.ai/code/session_01RsFxM9BWeMQUHzZzU2At2X

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Added Kubernetes architecture documentation detailing design approach and infrastructure layout.
  • Added development roadmap covering planned integration phases and delivery milestones.
  • Updated README to reference new architecture documentation.
  • Established docs/requirements/ folder to document forward-looking commitments.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 08e70fd6-50a3-446e-9855-48d7d5506a79

📥 Commits

Reviewing files that changed from the base of the PR and between c87f9cb and b08cc77.

📒 Files selected for processing (4)

• README.md
• docs/requirements/README.md
• docs/requirements/k8s-architecture.md
• docs/requirements/roadmap.md

---

📝 Walkthrough

Walkthrough

This PR introduces forward-looking architecture and delivery documentation by adding a new docs/requirements/ folder containing an index, a detailed Kubernetes architecture specification, and a six-phase implementation roadmap. The main README is also updated with a brief reference to the planned architecture. All changes are documentation-only and establish the planning foundation for Kubernetes-native deployment while maintaining Docker Compose as the supported path.

Changes

Kubernetes Architecture Planning

Layer / File(s)	Summary
Documentation Index README.md, docs/requirements/README.md	Forward-looking note added to main README; new requirements folder index clarifies that documents are architecture plans subject to revision as prototypes land, not current behavior or bug backlogs.
Kubernetes Architecture Design docs/requirements/k8s-architecture.md	Target Kubernetes architecture defined, including goals/non-goals, orchestrator/RuntimeBackend abstraction, four-tier storage model (image, squashfs skills, ephemeral/persistent home, S3 user data via FUSE), warm-pool mechanism, isolation runtime classes, network/security posture, cleanup responsibilities, and API surface invariants.
Phased Delivery Roadmap docs/requirements/roadmap.md	Six-phase roadmap from runtime abstraction refactor (Phase 1) through Kubernetes backend + Helm (Phase 4), warm pool (Phase 5), and optional VM isolation (Phase 6); includes guiding principles, per-phase exit criteria, tracking structure, and explicit cross-phase compatibility commitments for Docker Compose, MCP, and Open WebUI.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🐰 A rabbit hops through the plans with glee,
Kubernetes dreams in docs/ decree,
Phases unfold, one small step at a time,
Docker stays steady—no forced paradigm climb! 🚀

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/k8s-friendly-setup-Sar9D

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}