# 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