# rdev Architecture

rdev is a remote development API that enables secure command execution in isolated Kubernetes pods. This document provides an overview of the system architecture.

## System Context

```
                    ┌─────────────────────────────────────────────────┐
                    │                   rdev API                       │
                    │                                                  │
    ┌──────────┐    │  ┌──────────┐   ┌───────────┐   ┌───────────┐  │    ┌──────────┐
    │  Client  │────┼─▶│   HTTP   │──▶│  Service  │──▶│  Adapter  │──┼───▶│   K8s    │
    │  (SDK)   │◀───┼──│ Handler  │◀──│   Layer   │◀──│   Layer   │◀─┼────│  Cluster │
    └──────────┘    │  └──────────┘   └───────────┘   └───────────┘  │    └──────────┘
                    │       │              │               │          │
                    │       │              │               │          │
                    │       ▼              ▼               ▼          │
                    │  ┌──────────┐   ┌───────────┐   ┌───────────┐  │
                    │  │   Auth   │   │  Domain   │   │  Postgres │  │
                    │  │Middleware│   │  Models   │   │    DB     │  │
                    │  └──────────┘   └───────────┘   └───────────┘  │
                    └─────────────────────────────────────────────────┘
```

## Key Components

### HTTP Layer
- **Handlers**: REST endpoints for projects, commands, SSE streaming, API keys
- **Middleware**: Authentication, rate limiting, metrics, logging
- **Validation**: Input sanitization, command filtering

### Service Layer
- **ProjectService**: Project lifecycle management
- **AuthService**: API key management, validation

### Adapter Layer
- **Kubernetes Executor**: Command execution via kubectl exec
- **Project Repository**: Pod discovery, status monitoring
- **Postgres Repository**: API key storage

### Domain
- **Models**: Project, Command, APIKey, Scope
- **Errors**: Domain-specific error types
- **Events**: Command output, completion events

## Architecture Patterns

### Hexagonal Architecture (Ports & Adapters)

See [hexagonal.md](hexagonal.md) for detailed explanation.

```
        ┌─────────────────────────────────────────────┐
        │              Application Core               │
        │  ┌───────────────────────────────────────┐  │
        │  │           Domain Models                │  │
        │  │  (Project, Command, APIKey, Scope)     │  │
        │  └───────────────────────────────────────┘  │
        │  ┌───────────────────────────────────────┐  │
        │  │           Port Interfaces              │  │
        │  │  (ProjectRepository, Executor, etc.)   │  │
        │  └───────────────────────────────────────┘  │
        │  ┌───────────────────────────────────────┐  │
        │  │           Service Layer                │  │
        │  │  (ProjectService, uses ports)          │  │
        │  └───────────────────────────────────────┘  │
        └───────────────────┬─────────────────────────┘
                            │
        ┌───────────────────┴─────────────────────────┐
        │              Adapters                        │
        │  ┌─────────────┐  ┌─────────────┐           │
        │  │  Kubernetes │  │   Postgres  │           │
        │  │   Adapter   │  │   Adapter   │           │
        │  └─────────────┘  └─────────────┘           │
        └─────────────────────────────────────────────┘
```

### Key Flows

1. **Command Execution**: Client -> Handler -> Service -> Executor -> K8s Pod
2. **SSE Streaming**: Command output -> StreamManager -> SSE Response
3. **Authentication**: Request -> Middleware -> AuthService -> DB Lookup

See [streaming.md](streaming.md) and [security.md](security.md) for details.

## Technology Stack

| Component | Technology |
|-----------|------------|
| Language | Go 1.22+ |
| HTTP Router | chi v5 |
| Database | PostgreSQL |
| Container Orchestration | Kubernetes |
| Metrics | Prometheus |
| Tracing | OpenTelemetry (optional) |

## Package Structure

```
internal/
├── adapter/           # Infrastructure adapters
│   ├── cached/       # Caching wrappers
│   └── kubernetes/   # K8s client implementation
├── auth/             # Authentication & authorization
├── circuitbreaker/   # Circuit breaker for resilience
├── db/               # Database connectivity
├── domain/           # Core domain models
├── handlers/         # HTTP handlers
├── metrics/          # Prometheus metrics
├── port/             # Port interfaces (abstractions)
├── ratelimit/        # Rate limiting
├── sanitize/         # Command sanitization
├── service/          # Business logic services
└── validate/         # Input validation

pkg/
└── api/              # Shared API utilities

cmd/
└── rdev-api/         # Main application entry point
```

## Configuration

Environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | HTTP server port | 8080 |
| `POSTGRES_HOST` | Database host | postgres.databases.svc |
| `POSTGRES_DB` | Database name | rdev |
| `RDEV_NAMESPACE` | K8s namespace for pods | default |
| `RATE_LIMIT_RPS` | Requests per second limit | 10 |
| `CONCURRENT_COMMANDS` | Max concurrent commands | 5 |

## Related Documentation

- [Hexagonal Architecture](hexagonal.md) - Port/Adapter pattern details
- [Security](security.md) - Auth, sanitization, rate limiting
- [Streaming](streaming.md) - SSE protocol, reconnection handling