154 lines
4.0 KiB
Markdown
154 lines
4.0 KiB
Markdown
# 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
|
||
```bash
|
||
cd client
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
#### Backend
|
||
```bash
|
||
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 |