opencode-krates-connector/README.md

Krates - Kubernetes Workspace Explorer

A collaborative, real-time Kubernetes workspace explorer with an infinite canvas interface.

Architecture

Frontend

• Framework: React 18 + TypeScript
• Styling: Inline styles (CSS-in-JS)
• Terminal: xterm.js
• Real-Time: Yjs + y-websocket (CRDT collaboration)
• Build Tool: Vite
• State: Zustand

Backend

• Language: Go
• Kubernetes Client: kubernetes/client-go
• WebSockets: gorilla/websocket
• CRDT: Yjs + y-websocket

Project Structure

krates/
├── client/                     # Frontend application
│   ├── src/
│   │   ├── components/         # React components
│   │   │   ├── canvas/        # Canvas and world layer
│   │   │   ├── krate/         # Krate and windows
│   │   │   └── shared/        # Shared components
│   │   ├── hooks/             # Custom React hooks
│   │   ├── state/             # Zustand state stores
│   │   ├── utils/             # Utility functions
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── public/                 # Static assets
│   └── package.json
│
├── server/                     # Backend service
│   ├── cmd/server/             # Main server entry point
│   │   └── main.go
│   ├── internal/
│   │   ├── api/               # HTTP endpoints
│   │   │   ├── handlers/
│   │   │   └── routes.go
│   │   ├── ws/                # WebSocket handlers
│   │   │   ├── shell.go
│   │   │   ├── logs.go
│   │   │   ├── watch.go
│   │   │   └── sync.go
│   │   ├── k8s/               # Kubernetes client wrappers
│   │   │   ├── client.go
│   │   │   ├── resources.go
│   │   │   └── watch.go
│   │   ├── crdt/              # Yjs integration
│   │   │   └── provider.go
│   │   └── auth/              # Authentication
│   │       └── token.go
│   └── go.mod
│
└── design/                     # Design documentation
    ├── canvas.md
    ├── spotlight.md
    ├── krate.md
    ├── detail-window.md
    ├── top-bar.md
    ├── admin-drawer.md
    ├── minimap.md
    ├── backend.md
    ├── architecture.md
    └── shell-logs.md

Development

Prerequisites

• Node.js 20+
• Go 1.21+
• Kubernetes cluster (or access to one)

Setup

Frontend

cd client
npm install
npm run dev

Backend

cd server
go mod download
go run cmd/server/main.go

Features

Canvas Workspace

• Infinite 12000×8000px canvas
• Pan/zoom navigation
• Level of Detail (LOD) rendering
• Grid overlay

Krate System

• Group related windows together
• Auto-fit frame around windows
• Non-overlapping placement
• Minimize/expand support

Window Types

• Detail Window: YAML, Describe, Logs, Shell views
• Collection Window: List/Tree view of multiple resources
• Resize/move within krate
• Maximize functionality

Real-Time Collaboration

• Multi-user presence
• Shared workspace state (Yjs CRDT)
• Real-time shell sessions
• Log streaming

Kubernetes Integration

• Pod, Deployment, Service, Namespace resources
• Live resource watching
• Shell into pods
• Stream pod logs
• Namespace filtering

Design Files

See the design/ folder for comprehensive specifications:

• canvas.md - Canvas and navigation
• spotlight.md - Search and discovery
• krate.md - Window grouping
• detail-window.md - Individual window views
• collection-window.md - Resource collections
• top-bar.md - Status and navigation
• admin-drawer.md - User management
• minimap.md - Navigation overview
• backend.md - Backend architecture
• architecture.md - Overall architecture

Contributing

1. Create a branch from design
2. Make commits with clear messages
3. Test thoroughly
4. Merge back to design
5. Periodically merge design to main

License

MIT