Gemini Context: RCoder Project

This document provides a comprehensive overview of the rcoder project, its architecture, and development conventions to be used as instructional context for Gemini.

1. Project Overview

RCoder is a sophisticated, Rust-based AI-driven development platform. It functions as a central orchestrator that can manage and communicate with various AI coding agents. The system is designed with a modern microservices-style architecture, leveraging containerization for both its own components and the agents it manages.

Key Technologies

Language: Rust (2021 Edition, Workspace)
Backend Frameworks:
- HTTP: axum (for the main REST API and SSE)
- gRPC: tonic (for internal service-to-service communication)
Reverse Proxy: pingora for high-performance routing.
Containerization: Docker & Docker Compose.
Core Libraries: tokio (async runtime), serde (serialization), clap (CLI parsing), tracing (structured logging), bollard (Docker API interaction).

Architecture

The project consists of two primary services, typically run in Docker containers:

rcoder (HTTP Gateway / Orchestrator):
- Exposes a public REST API for clients (e.g., /chat).
- Provides real-time progress updates via Server-Sent Events (SSE).
- Acts as a gRPC client, forwarding requests to the agent_runner.
- Manages the lifecycle of agent containers using the Docker daemon (via a mounted Docker socket).
- Includes an optional pingora reverse proxy for flexible routing to other local services.
agent_runner (gRPC Service / Worker):
- The core backend service that exposes a gRPC API defined in agent.proto.
- Receives tasks from the rcoder service.
- Executes the actual AI agent logic.
- Streams progress events back to rcoder via a gRPC server-streaming RPC.
- Note: The agent_runner binary can run in different modes. It is used as the executable for both the rcoder (full mode) and agent_runner (agent-only mode) services.

Communication

External: Clients communicate with the rcoder service via a standard REST API and consume a Server-Sent Events (SSE) stream for progress.
Internal: The rcoder gateway communicates with the agent_runner service using a well-defined, type-safe gRPC API. The API contract is located at crates/shared_types/proto/agent.proto.

2. Building and Running

The project is designed to be run within a containerized environment using Docker Compose. The Makefile provides convenient scripts for the entire development lifecycle.

Primary Workflow (Docker)

The recommended workflow for development is:

First-time Setup: Build the main Docker image.
```
make dev-build
```
Start Services: Launch the services using Docker Compose.
```
make dev-up
```
View Logs: Tail the logs from the running services.
```
make dev-logs
```
Make Code Changes: After modifying the Rust source code, restart the services. This command quickly rebuilds the image and restarts the containers.
```
make dev-restart
```
Stop Services: Shut down the Docker Compose environment.
```
make dev-down
```

Local (Non-Docker) Builds

While the primary workflow is container-based, you can also build and install the binaries locally.

Build release binaries:
```
cargo build --release --workspace
```
(The main binary is target/release/rcoder)
Install binaries to ~/.cargo/bin:
```
make install
```

3. Development Conventions

Workspace Structure: The project is a Rust workspace located in the crates/ directory. Shared types, especially gRPC definitions, are in the crates/shared_types crate.
Configuration: The system uses a layered configuration approach (CLI arguments > Environment Variables > config.yml), with the base configuration defined in config.yml.
API First Design:
- Internal APIs are defined using Protobuf in crates/shared_types/proto/agent.proto. Any changes to internal communication should start here.
- External APIs are RESTful, with routes defined in crates/rcoder/src/router.rs.

Code Style: The project follows standard Rust conventions. Use the following commands to maintain code quality:

# Format the entire workspace
cargo fmt

# Lint the entire workspace
cargo clippy --workspace --all-targets

Containerization: The application is container-aware. It interacts directly with the Docker socket to manage other containers. The docker-compose.yml and docker/Dockerfile files define the development and production environments.
Logging: Structured logging is implemented via the tracing crate. Logs are output to both the console and to rolling files in the logs/ directory inside the container (which is volume-mounted to the host).

5.0 KiB Raw Blame History