diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md new file mode 100644 index 0000000..79aff42 --- /dev/null +++ b/docs/API_REFERENCE.md @@ -0,0 +1,483 @@ +# OpenKommander API Reference + +## Overview + +The OpenKommander REST API provides programmatic access to Kafka cluster management operations. All endpoints return JSON responses and follow RESTful conventions. + +**Base URL**: `http://localhost:8081/api/v1/{broker}` + +**Note**: Most endpoints require a `{broker}` path parameter specifying the broker address (e.g., `localhost:9092`). + +**Content-Type**: `application/json` + +## Authentication + +Currently, the API does not require authentication. Access control is managed through Kafka broker security settings. + +## Response Format + +### Success Response +```json +{ + "status": "ok", + "data": { ... } +} +``` + +### Error Response +```json +{ + "status_code": 404, + "message": "Resource not found", + "error": "detailed error message" +} +``` + +## Common HTTP Status Codes + +| Code | Meaning | Description | +|------|---------|-------------| +| 200 | OK | Request successful | +| 201 | Created | Resource created successfully | +| 202 | Accepted | Request accepted for processing | +| 400 | Bad Request | Invalid request parameters | +| 404 | Not Found | Resource not found | +| 409 | Conflict | Resource already exists | +| 500 | Internal Server Error | Server error occurred | + +--- + +## Health & Status Endpoints + +### Health Check + +Check if the API is running and healthy. + +**Endpoint**: `GET /{broker}/health` + +**Path Parameters**: +- `broker` (string): Broker address (e.g., `localhost:9092`) + +**Response**: +```json +{ + "status": "ok", + "message": "Health check successful" +} +``` + +**Example**: +```bash +curl http://localhost:8081/api/v1/localhost:9092/health +``` + +--- + +## Broker Endpoints + +### List Brokers + +Get information about all brokers in the cluster. + +**Endpoint**: `GET /{broker}/brokers` + +**Path Parameters**: +- `broker` (string): Broker address (e.g., `localhost:9092`) + +**Response**: +```json +{ + "status": "ok", + "data": [ + { + "id": 1, + "addr": "localhost:9092", + "connected": true, + "rack": "", + "state": null + } + ] +} +``` + +**Response Fields**: +- `id` (integer): Broker ID +- `addr` (string): Broker address +- `connected` (boolean): Connection status +- `rack` (string): Rack assignment +- `state` (object): TLS connection state (if applicable) + +**Example**: +```bash +curl http://localhost:8081/api/v1/localhost:9092/brokers +``` + +--- + +## Cluster Endpoints + +### List Clusters + +Get information about all available clusters/brokers. + +**Endpoint**: `GET /clusters` + +**Response**: +```json +{ + "status": "ok", + "data": [ + { + "id": 1, + "address": "localhost:9092", + "status": "Connected", + "rack": "rack-1", + "connected": true + } + ] +} +``` + +**Response Fields**: +- `id` (integer): Cluster/broker ID +- `address` (string): Network address (host:port) +- `status` (string): Connection status ("Connected" or "Disconnected") +- `rack` (string): Rack assignment (or "N/A") +- `connected` (boolean): Connection state + +**Example**: +```bash +curl http://localhost:8081/api/v1/clusters +``` + +### Get Cluster Metadata + +Get detailed metadata about a specific cluster. + +**Endpoint**: `GET /clusters/{clusterId}/metadata` + +**Path Parameters**: +- `clusterId` (string): The cluster identifier + +**Response**: +```json +{ + "status": "ok", + "data": { + "broker_count": 3, + "cluster_id": "openkommander-client", + "brokers": [ + { + "id": 1, + "address": "localhost:9092", + "connected": true, + "rack": "rack-1" + } + ] + } +} +``` + +**Example**: +```bash +curl http://localhost:8081/api/v1/clusters/1/metadata +``` + +--- + +## Topic Endpoints + +### List Topics + +Get all topics in the cluster. + +**Endpoint**: `GET /topics` + +**Response**: +```json +[ + { + "name": "test-topic", + "partitions": 3, + "replication_factor": 1, + "internal": false, + "replicas": 3, + "in_sync_replicas": 3, + "cleanup_policy": "delete" + } +] +``` + +**Response Fields**: +- `name` (string): Topic name +- `partitions` (integer): Number of partitions +- `replication_factor` (integer): Replication factor +- `internal` (boolean): Whether topic is internal +- `replicas` (integer): Total replicas +- `in_sync_replicas` (integer): In-sync replicas +- `cleanup_policy` (string): Cleanup policy ("delete" or "compact") + +**Example**: +```bash +curl http://localhost:8081/api/v1/topics +``` + +### Create Topic + +Create a new Kafka topic. + +**Endpoint**: `POST /topics` + +**Request Body**: +```json +{ + "name": "new-topic", + "partitions": 3, + "replication_factor": 1 +} +``` + +**Request Fields**: +- `name` (string, required): Topic name +- `partitions` (integer, required): Number of partitions (min: 1) +- `replication_factor` (integer, required): Replication factor (min: 1) + +**Response**: +```json +{ + "status": "created" +} +``` + +**Example**: +```bash +curl -X POST http://localhost:8081/api/v1/topics \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-topic", + "partitions": 3, + "replication_factor": 1 + }' +``` + +**Error Responses**: +- `400`: Invalid parameters (partitions < 1, replication_factor > broker count) +- `500`: Topic already exists or creation failed + +### Get Topic Details + +Get detailed information about a specific topic. + +**Endpoint**: `GET /topics/{name}` + +**Path Parameters**: +- `name` (string): Topic name + +**Response**: +```json +{ + "name": "test-topic", + "partitions": 3, + "replication_factor": 1, + "partition_ids": [0, 1, 2] +} +``` + +**Example**: +```bash +curl http://localhost:8081/api/v1/topics/test-topic +``` + +### Delete Topic + +Delete an existing topic. + +**Endpoint**: `DELETE /topics/{name}` + +**Path Parameters**: +- `name` (string): Topic name + +**Response**: +```json +{ + "status": "deleted" +} +``` + +**Example**: +```bash +curl -X DELETE http://localhost:8081/api/v1/topics/test-topic +``` + +**Error Responses**: +- `500`: Deletion failed + +--- + +## Error Handling + +### Error Response Format + +All errors follow this format: + +```json +{ + "status_code": 404, + "message": "User-friendly error message", + "error": "Detailed technical error" +} +``` + +### Common Errors + +#### 400 Bad Request +```json +{ + "status_code": 400, + "message": "Invalid request parameters", + "error": "Partitions must be greater than 0" +} +``` + +#### 404 Not Found +```json +{ + "status_code": 404, + "message": "Topic 'test-topic' not found", + "error": "resource not found" +} +``` + +#### 409 Conflict +```json +{ + "status_code": 409, + "message": "Consumer ID already exists", + "error": "duplicate resource" +} +``` + +#### 500 Internal Server Error +```json +{ + "status_code": 500, + "message": "Error connecting to cluster", + "error": "connection refused" +} +``` + +--- + +## Rate Limiting + +Currently, there are no rate limits enforced. For production use, consider implementing rate limiting at the reverse proxy level. + +--- + +## CORS + +The API supports CORS for web browser access. Configure CORS settings based on your deployment requirements. + +--- + +## Pagination + +Currently, the API does not support pagination. All list endpoints return complete results. For large datasets, consider implementing pagination in future versions. + +--- + +## Versioning + +The API is versioned through the URL path (`/api/v1`). Breaking changes will result in a new version (`/api/v2`). + +--- + +## SDK Examples + +### JavaScript/Node.js + +```javascript +const axios = require('axios'); + +const api = axios.create({ + baseURL: 'http://localhost:8081/api/v1', + headers: { 'Content-Type': 'application/json' } +}); + +// List topics +const topics = await api.get('/topics'); +console.log(topics.data); + +// Create topic +await api.post('/topics', { + name: 'my-topic', + partitions: 3, + replication_factor: 1 +}); + +// Produce message +await api.post('/messages/my-topic', { + message: 'Hello, Kafka!' +}); +``` + +### Python + +```python +import requests + +BASE_URL = 'http://localhost:8081/api/v1' + +# List topics +response = requests.get(f'{BASE_URL}/topics') +topics = response.json() + +# Create topic +requests.post(f'{BASE_URL}/topics', json={ + 'name': 'my-topic', + 'partitions': 3, + 'replication_factor': 1 +}) + +# Produce message +requests.post(f'{BASE_URL}/messages/my-topic', json={ + 'message': 'Hello, Kafka!' +}) +``` + +### cURL + +```bash +# List topics +curl http://localhost:8081/api/v1/topics + +# Create topic +curl -X POST http://localhost:8081/api/v1/topics \ + -H "Content-Type: application/json" \ + -d '{"name":"my-topic","partitions":3,"replication_factor":1}' + +# Produce message +curl -X POST http://localhost:8081/api/v1/messages/my-topic \ + -H "Content-Type: application/json" \ + -d '{"message":"Hello, Kafka!"}' +``` + +--- + +## WebSocket Support + +WebSocket support is planned for future releases to enable real-time updates without polling. + +--- + +## OpenAPI Specification + +The complete OpenAPI 3.0 specification is available at `docs/openapi.yaml`. You can use tools like Swagger UI or Postman to explore the API interactively. + +--- + +## Support + +For API issues or questions: +- GitHub Issues: https://github.com/IBM/openkommander/issues +- Documentation: `/docs` directory \ No newline at end of file diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..acb0ccd --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,433 @@ +# OpenKommander Architecture + +## System Architecture Overview + +OpenKommander follows a three-tier architecture with a Go backend, REST API layer, and React frontend, all designed to interact with Apache Kafka clusters. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Users │ +└────────────┬────────────────────────────┬───────────────────┘ + │ │ + │ CLI │ Web Browser + │ │ +┌────────────▼────────────┐ ┌───────────▼──────────────────┐ +│ CLI Interface (ok) │ │ React Frontend (Web UI) │ +│ - Cobra Commands │ │ - Carbon Design System │ +│ - Interactive Prompts │ │ - Real-time Dashboard │ +│ - Formatted Output │ │ - Resource Management │ +└────────────┬────────────┘ └───────────┬──────────────────┘ + │ │ + │ │ HTTP/REST + │ │ +┌────────────▼────────────────────────────▼──────────────────┐ +│ Go Backend Application │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ REST API Server (HTTP) │ │ +│ │ - Health endpoints │ │ +│ │ - Topic management │ │ +│ │ - Broker information │ │ +│ │ - Consumer group data │ │ +│ │ - Message production │ │ +│ └─────────────────┬───────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────▼───────────────────────────────────┐ │ +│ │ Core Business Logic Layer │ │ +│ │ - commands/broker.go │ │ +│ │ - commands/cluster.go │ │ +│ │ - commands/topic.go │ │ +│ │ - commands/produce.go │ │ +│ │ - commands/status.go │ │ +│ └─────────────────┬───────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────▼───────────────────────────────────┐ │ +│ │ Session Management Layer │ │ +│ │ - Session persistence │ │ +│ │ - Client connection pooling │ │ +│ │ - Authentication state │ │ +│ └─────────────────┬───────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────▼───────────────────────────────────┐ │ +│ │ Kafka Client Layer (Sarama) │ │ +│ │ - ClusterAdmin interface │ │ +│ │ - Client interface │ │ +│ │ - Producer interface │ │ +│ └─────────────────┬───────────────────────────────────┘ │ +└────────────────────┼────────────────────────────────────────┘ + │ + │ Kafka Protocol + │ +┌────────────────────▼────────────────────────────────────────┐ +│ Apache Kafka Cluster(s) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Broker 1 │ │ Broker 2 │ │ Broker 3 │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ Topics, Partitions, Consumer Groups, Messages │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Component Details + +### 1. Frontend Layer (React) + +#### Technology Stack +- **React 18**: Modern React with hooks and concurrent features +- **Vite**: Fast build tool and dev server +- **Carbon Design System**: IBM's enterprise UI framework +- **React Router v6**: Client-side routing +- **Axios**: HTTP client for API calls + +#### Key Components + +##### Layout Components +- **MainLayout**: Main application shell with navigation +- **AppSideNav**: Sidebar navigation menu + +##### Page Components +- **OverviewPage**: Dashboard with cluster metrics +- **TopicsPage**: Topic management interface +- **BrokersPage**: Broker information display +- **ConsumerGroupsPage**: Consumer group monitoring + +##### Common Components +- **BaseTable**: Reusable data table component +- **BaseModal**: Modal dialog wrapper +- **ResourcePage**: Generic resource management page +- **StatusTag**: Status indicator component +- **ErrorNotification**: Error display component + +##### Custom Hooks +- **useApi**: API call management with loading/error states +- **useResourceManager**: CRUD operations for resources + +##### Services +- **api.js**: Centralized API client +- **localstorage.js**: Browser storage utilities + +#### Data Flow +``` +User Action → Component → Hook → API Service → Backend + ↓ + State Update + ↓ + Re-render +``` + +### 2. Backend Layer (Go) + +#### Package Structure + +##### Main Package (`main.go`) +- Application entry point +- Logger initialization +- CLI command execution + +##### CLI Package (`pkg/cli/`) +- Cobra command definitions +- Command routing +- User input handling +- Output formatting + +##### Core Commands (`internal/core/commands/`) + +**broker.go** +- `GetBrokerClient()`: Retrieve Kafka client for broker operations + +**cluster.go** +- `ListClusters()`: Get all cluster/broker information +- `GetClusterMetadata()`: Retrieve cluster metadata + +**topic.go** +- `CreateTopic()`: Create new topics +- `DeleteTopic()`: Remove topics +- `ListTopics()`: Get all topics +- `DescribeTopic()`: Get topic details +- `DescribeTopicConfig()`: Get topic configuration +- `UpdateTopic()`: Modify topic partitions + +**produce.go** +- `ProduceMessage()`: Send messages to topics + +**status.go** +- `GetAdminClient()`: Get Sarama admin client +- `GetClient()`: Get Sarama client +- `NewFailure()`: Error handling utility + +##### Session Package (`pkg/session/`) +- Session state management +- Broker connection persistence +- Client lifecycle management + +##### Logger Package (`pkg/logger/`) +- Structured logging +- Configurable log levels +- Pretty formatting for development + +#### Error Handling + +Custom `Failure` type for consistent error responses: +```go +type Failure struct { + Err error + HttpCode int +} +``` + +All command functions return `(result, *Failure)` for uniform error handling. + +### 3. REST API Layer + +#### API Design + +**Base URL**: `/api/v1` + +**Response Format**: +```json +{ + "status": "ok|error", + "data": { ... }, + "message": "..." +} +``` + +#### Endpoint Categories + +##### Health & Status +- `GET /health`: API health check +- `GET /status`: Broker status + +##### Cluster Management +- `GET /clusters`: List all clusters +- `GET /clusters/{id}/metadata`: Get cluster metadata + +##### Broker Management +- `GET /brokers`: List all brokers + +##### Topic Management +- `GET /topics`: List all topics +- `POST /topics`: Create topic +- `GET /topics/{name}`: Get topic details +- `DELETE /topics/{name}`: Delete topic + +##### Consumer Groups +- `GET /consumers`: List consumer groups +- `GET /consumers/{group}`: Get group details + +##### Message Production +- `POST /messages/{topic}`: Produce message + +### 4. Kafka Integration Layer + +#### Sarama Client Usage + +**ClusterAdmin Interface**: +- Topic CRUD operations +- Configuration management +- Partition management + +**Client Interface**: +- Broker discovery +- Metadata retrieval +- Connection management + +**Producer Interface**: +- Message production +- Partition selection +- Acknowledgment handling + +#### Connection Management + +```go +// Session maintains Kafka connections +type Session struct { + brokers []string + client sarama.Client + adminClient sarama.ClusterAdmin + authenticated bool +} +``` + +## Data Flow Patterns + +### 1. CLI Command Flow + +``` +User Input → Cobra Command → Core Command Function → Sarama Client → Kafka + ↓ +User Output ← Formatted Response ← Result/Error ← Response ← Kafka +``` + +### 2. Web UI Flow + +``` +User Action → React Component → API Call → REST Handler → Core Command → Sarama → Kafka + ↓ +UI Update ← State Update ← JSON Response ← HTTP Response ← Result ← Response ← Kafka +``` + +### 3. Real-time Metrics Flow + +``` +Timer → API Poll → Multiple Endpoints → Aggregate Data → Update State → Re-render + ↓ +3s interval +``` + +## Deployment Architecture + +### Development Environment + +``` +┌─────────────────────────────────────────────────────────┐ +│ Docker/Podman Compose Environment │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Kafka │ │ Kafka │ │ Kafka │ │ +│ │ Cluster 1 │ │ Cluster 2 │ │ Cluster 3 │ │ +│ │ :9092 │ │ :9095 │ │ :9098 │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ OpenKommander Container │ │ +│ │ - Go Backend │ │ +│ │ - React Frontend (built) │ │ +│ │ - Port 8081 │ │ +│ └──────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +### Production Deployment Options + +#### Option 1: Standalone Binary +``` +OpenKommander CLI → Kafka Cluster(s) +``` + +#### Option 2: Containerized Service +``` +Container (Go + Frontend) → Load Balancer → Kafka Cluster(s) +``` + +#### Option 3: Kubernetes Deployment +``` +K8s Pod (OpenKommander) → K8s Service → Kafka StatefulSet +``` + +## Security Architecture + +### Authentication Flow +``` +User → Login Command → Session Creation → Broker Connection → Authenticated Session +``` + +### Session Security +- Session data stored in `~/.ok/` +- File permissions restrict access +- No passwords stored (relies on Kafka security) + +### API Security +- CORS configuration for web access +- Session validation for all operations +- No built-in authentication (delegates to Kafka) + +## Scalability Considerations + +### Backend +- Stateless REST API (horizontal scaling possible) +- Connection pooling for Kafka clients +- Efficient session management + +### Frontend +- Code splitting for faster loads +- Lazy loading of components +- Optimized bundle size + +### Kafka Integration +- Multiple broker support +- Partition-aware operations +- Efficient metadata caching + +## Performance Optimizations + +### Backend +- Connection reuse via session management +- Minimal memory footprint +- Fast JSON serialization +- Efficient error handling + +### Frontend +- Virtual scrolling for large tables +- Debounced API calls +- Optimistic UI updates +- Configurable polling intervals + +### Kafka Operations +- Batch operations where possible +- Efficient metadata queries +- Smart partition selection + +## Monitoring & Observability + +### Logging +- Structured logging with levels (Debug, Info, Warn, Error) +- Configurable output format (pretty/JSON) +- Request/response logging in API + +### Metrics (Available via UI) +- Broker count +- Topic count +- Messages per minute +- Consumer lag +- Cluster health status + +### Error Tracking +- Consistent error format +- HTTP status codes +- User-friendly error messages +- Stack traces in debug mode + +## Technology Decisions + +### Why Go? +- Excellent Kafka client library (Sarama) +- Fast compilation and execution +- Strong concurrency support +- Easy deployment (single binary) + +### Why React? +- Component reusability +- Large ecosystem +- Excellent developer experience +- Strong community support + +### Why Carbon Design System? +- Enterprise-grade components +- Accessibility built-in +- Consistent design language +- IBM backing and support + +### Why Sarama? +- Mature and stable +- Full Kafka protocol support +- Active maintenance +- Production-proven + +## Future Architecture Enhancements + +### Planned Improvements +1. **Microservices Split**: Separate API and worker services +2. **Message Queue**: Add async job processing +3. **Caching Layer**: Redis for metadata caching +4. **Database**: Persist metrics and history +5. **Authentication**: OAuth2/OIDC integration +6. **Multi-tenancy**: Support multiple users +7. **WebSocket**: Real-time updates without polling +8. **Schema Registry**: Avro/Protobuf support + +### Scalability Roadmap +1. Horizontal scaling of API servers +2. Load balancing for high availability +3. Distributed session management +4. Metrics aggregation service +5. Historical data storage and analysis \ No newline at end of file diff --git a/docs/DEVELOPMENT_GUIDE.md b/docs/DEVELOPMENT_GUIDE.md new file mode 100644 index 0000000..44efcd3 --- /dev/null +++ b/docs/DEVELOPMENT_GUIDE.md @@ -0,0 +1,788 @@ +# OpenKommander Development Guide + +## Table of Contents + +1. [Development Environment Setup](#development-environment-setup) +2. [Project Structure](#project-structure) +3. [Building the Project](#building-the-project) +4. [Running Tests](#running-tests) +5. [Development Workflow](#development-workflow) +6. [Code Style Guidelines](#code-style-guidelines) +7. [Contributing](#contributing) +8. [Debugging](#debugging) +9. [Release Process](#release-process) + +--- + +## Development Environment Setup + +### Prerequisites + +- **Go**: Version 1.24 or higher +- **Node.js**: Version 18 or higher +- **npm**: Version 9 or higher +- **Make**: GNU Make +- **Podman** or **Docker**: For containerized development +- **Git**: Version control + +### Initial Setup + +1. **Clone the repository**: + ```bash + git clone https://github.com/IBM/openkommander.git + cd openkommander + ``` + +2. **Install Go dependencies**: + ```bash + make setup + ``` + +3. **Install frontend dependencies**: + ```bash + cd frontend + npm install + cd .. + ``` + +4. **Start development environment**: + ```bash + make container-start + ``` + +5. **Verify setup**: + ```bash + make container-logs + ``` + +### IDE Setup + +#### VS Code + +Recommended extensions: +- Go (golang.go) +- ESLint (dbaeumer.vscode-eslint) +- Prettier (esbenp.prettier-vscode) +- Docker (ms-azuretools.vscode-docker) + +**Settings** (`.vscode/settings.json`): +```json +{ + "go.useLanguageServer": true, + "go.lintTool": "golangci-lint", + "editor.formatOnSave": true, + "go.formatTool": "goimports", + "[javascript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[javascriptreact]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + } +} +``` + +#### GoLand / IntelliJ IDEA + +1. Open project directory +2. Enable Go modules support +3. Configure Go SDK (1.24+) +4. Enable ESLint for frontend code + +--- + +## Project Structure + +``` +openkommander/ +├── internal/ # Internal packages (not importable) +│ └── core/ +│ └── commands/ # Core business logic +│ ├── broker.go # Broker operations +│ ├── cluster.go # Cluster management +│ ├── topic.go # Topic operations +│ ├── produce.go # Message production +│ └── status.go # Status and error handling +├── pkg/ # Public packages (importable) +│ ├── cli/ # CLI implementation +│ ├── cluster/ # Cluster utilities +│ ├── constants/ # Application constants +│ ├── logger/ # Logging utilities +│ ├── rest/ # REST API server +│ └── session/ # Session management +├── frontend/ # React web application +│ ├── src/ +│ │ ├── components/ # React components +│ │ │ ├── common/ # Reusable components +│ │ │ ├── layout/ # Layout components +│ │ │ └── overview/ # Overview-specific components +│ │ ├── pages/ # Page components +│ │ ├── services/ # API services +│ │ ├── hooks/ # Custom React hooks +│ │ └── config/ # Configuration +│ ├── public/ # Static assets +│ └── package.json # Frontend dependencies +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── tests/ # Test files +├── docker/ # Docker configurations +├── main.go # Application entry point +├── go.mod # Go module definition +├── go.sum # Go dependency checksums +├── Makefile # Build automation +└── README.md # Project README +``` + +### Key Directories + +- **`internal/core/commands/`**: Core Kafka operations +- **`pkg/cli/`**: CLI command definitions using Cobra +- **`pkg/session/`**: Session state management +- **`frontend/src/components/`**: React UI components +- **`frontend/src/services/`**: API client code + +--- + +## Building the Project + +### Backend (Go) + +**Build CLI binary**: +```bash +make build +``` + +Output: `./openkommander` (or `./openkommander.exe` on Windows) + +**Install CLI globally**: +```bash +sudo make install +``` + +Installs to: `/usr/local/bin/ok` + +**Development build and install**: +```bash +make dev-run +``` + +This runs: `setup` → `build` → `install` + +### Frontend (React) + +**Development server**: +```bash +cd frontend +npm run dev +``` + +Access at: `http://localhost:5173` + +**Production build**: +```bash +cd frontend +npm run build +``` + +Output: `frontend/dist/` + +**Build and copy to config directory**: +```bash +make frontend-build +``` + +Copies to: `~/.ok/frontend/` + +### Full Build + +Build both backend and frontend: +```bash +make build +make frontend-build +``` + +--- + +## Running Tests + +### Backend Tests + +**Run all tests**: +```bash +go test ./... +``` + +**Run tests with coverage**: +```bash +go test -cover ./... +``` + +**Run tests with verbose output**: +```bash +go test -v ./... +``` + +**Run specific package tests**: +```bash +go test ./internal/core/commands/ +``` + +**Generate coverage report**: +```bash +go test -coverprofile=coverage.out ./... +go tool cover -html=coverage.out +``` + +### Frontend Tests + +**Run tests**: +```bash +cd frontend +npm test +``` + +**Run tests with coverage**: +```bash +cd frontend +npm run test:coverage +``` + +**Run tests in watch mode**: +```bash +cd frontend +npm run test:watch +``` + +### Integration Tests + +See `tests/TESTING_GUIDELINES.md` for integration testing procedures. + +--- + +## Development Workflow + +### 1. Feature Development + +**Create a feature branch**: +```bash +git checkout -b feature/my-new-feature +``` + +**Make changes and test**: +```bash +# Backend changes +make build +./openkommander [command] + +# Frontend changes +cd frontend +npm run dev +``` + +**Commit changes**: +```bash +git add . +git commit -m "feat: add new feature" +``` + +### 2. Code Review Process + +1. Push branch to GitHub +2. Create Pull Request +3. Address review comments +4. Ensure CI passes +5. Merge when approved + +### 3. Local Testing + +**Start development environment**: +```bash +make container-start +``` + +**Execute into container**: +```bash +make container-exec +``` + +**View logs**: +```bash +make container-logs +``` + +**Stop environment**: +```bash +make container-stop +``` + +### 4. Hot Reload Development + +**Backend** (requires manual restart): +```bash +# Terminal 1: Watch for changes +make build && ./openkommander server start -p 8081 + +# Terminal 2: Make changes and rebuild +make build +``` + +**Frontend** (automatic hot reload): +```bash +cd frontend +npm run dev +# Changes auto-reload in browser +``` + +--- + +## Code Style Guidelines + +### Go Code Style + +**Follow standard Go conventions**: +- Use `gofmt` for formatting +- Use `golint` for linting +- Follow [Effective Go](https://golang.org/doc/effective_go.html) + +**Naming conventions**: +```go +// Good +func CreateTopic(name string) error { } +var topicName string + +// Avoid +func create_topic(name string) error { } +var topic_name string +``` + +**Error handling**: +```go +// Always check errors +result, err := someFunction() +if err != nil { + return nil, NewFailure(fmt.Sprintf("operation failed: %v", err), http.StatusInternalServerError) +} +``` + +**Comments**: +```go +// CreateTopic creates a new Kafka topic with the specified configuration. +// Returns success message and nil on success, or empty string and Failure on error. +func CreateTopic(topicName string, numPartitions, replicationFactor int) (string, *Failure) { + // Implementation +} +``` + +**Package organization**: +- Keep packages focused and cohesive +- Avoid circular dependencies +- Use internal packages for non-exported code + +### JavaScript/React Code Style + +**Use Prettier for formatting**: +```bash +cd frontend +npm run format +``` + +**ESLint for linting**: +```bash +cd frontend +npm run lint +``` + +**Component structure**: +```jsx +// Good: Functional component with hooks +import React, { useState, useEffect } from 'react'; + +const MyComponent = ({ prop1, prop2 }) => { + const [state, setState] = useState(null); + + useEffect(() => { + // Effect logic + }, []); + + return ( +
+ {/* JSX */} +
+ ); +}; + +export default MyComponent; +``` + +**Naming conventions**: +- Components: PascalCase (`MyComponent.jsx`) +- Hooks: camelCase with 'use' prefix (`useMyHook.jsx`) +- Utilities: camelCase (`apiClient.js`) +- Constants: UPPER_SNAKE_CASE (`API_BASE_URL`) + +**File organization**: +``` +components/ + MyComponent/ + MyComponent.jsx + MyComponent.scss + MyComponent.test.jsx +``` + +--- + +## Contributing + +### Before Contributing + +1. Read [CONTRIBUTING.md](../CONTRIBUTING.md) +2. Check [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) +3. Review existing issues and PRs +4. Discuss major changes in an issue first + +### Contribution Workflow + +1. **Fork the repository** +2. **Create a feature branch**: + ```bash + git checkout -b feature/my-feature + ``` +3. **Make your changes** +4. **Add tests** for new functionality +5. **Run tests**: + ```bash + go test ./... + cd frontend && npm test + ``` +6. **Commit with conventional commits**: + ```bash + git commit -m "feat: add new feature" + ``` +7. **Push to your fork**: + ```bash + git push origin feature/my-feature + ``` +8. **Create Pull Request** + +### Commit Message Format + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + + + +