Contributing to Riven

Repository Structure

The Riven AI platform is split across 14 repositories in the riven-private GitHub organization. Each repo owns a specific domain:

Development Workflow

cd ~/Desktop/riven-private
git clone [email protected]:riven-private/<repo-name>.git
cd <repo-name>

yarn install

git checkout -b feat/my-feature

yarn lint
yarn test
yarn build

git push -u origin feat/my-feature

Coding Standards

TypeScript

• Strict mode — All TypeScript projects use strict compiler settings.
• ESLint v9 — Flat config (eslint.config.js or eslint.config.mjs). Run yarn lint before committing.
• Package manager — Yarn 4 (Berry) with workspaces. Never use npm or pnpm.
• Generated code — Code in src/__generated__/ is excluded from lint and test coverage. Never edit generated files.
• Path aliases — @/* maps to the project root in Next.js apps.
• UI components — Always use shadcn/ui as the base. Customize via className and Tailwind — never modify shadcn source files.

Python

• Python 3.13+ — All Python projects target 3.13 or later.
• UV — Use UV for dependency management and virtual environments.
• Linting — Ruff for linting and formatting.
• Type hints — Required for all function signatures.

General

• ESM only — All Node.js packages use ECMAScript modules.
• No any — Avoid any types. Use unknown and narrow with type guards.
• Error handling — Use ConnectError with appropriate gRPC status codes for RPC errors.

Proto Conventions

Protocol Buffers are the source of truth for all service APIs. Follow these conventions:

Package Naming

// Pattern: riven.<domain>.v1
package riven.billing.v1;
package riven.pages.v1;
package riven.agents.v1;

Service Naming

// Service name matches the domain
service BillingService { ... }
service PagesService { ... }

Field Naming

message CreateItemRequest {
  string item_name = 1;       // snake_case for fields
  int32 max_retry_count = 2;  // descriptive names
  string org_id = 3;          // standard abbreviations OK
}

Workflow

1. Edit .proto files — Make your API changes in the proto definitions first.
2. Lint — Run riven proto lint to validate.
3. Check for breaking changes — Run riven proto breaking before publishing.
4. Generate — Run riven proto generate to update TypeScript/Python stubs.
5. Implement — Update the service implementation to match the new API.
6. Publish — Run riven proto publish to push to the registry.

Testing

TypeScript

• Unit tests — Jest with TypeScript. Place test files adjacent to source: service.test.ts next to service.ts.
• Integration tests — TestContainers for database tests (PostgreSQL, MongoDB). Configure in jest.globalSetup.ts.
• Frontend tests — Jest + jsdom + Testing Library + MSW for RPC mocking.
• Coverage — Aim for meaningful coverage of business logic. Generated code is excluded.

# Run all tests
yarn test
 
# Run tests in watch mode
yarn test --watch
 
# Run a specific test file
yarn test service.test.ts

Python

• Unit tests — pytest with Python 3.13+.
• Integration tests — TestContainers for database and service tests.

uv run pytest
uv run pytest tests/test_service.py -v

PR Process

Requirements

• CI must pass (lint, test, build)
• At least 1 code review approval
• No unresolved review comments
• Squash merge into main

CI Pipeline

When you push a branch, the CI pipeline automatically:

1. Installs dependencies
2. Runs lint checks
3. Runs the full test suite
4. Builds the project
5. Checks for proto breaking changes (if proto files changed)

Review Guidelines

When reviewing PRs:

• Verify the proto API design follows conventions (if applicable)
• Check for test coverage of new business logic
• Ensure no secrets or credentials are committed
• Verify error handling uses appropriate status codes
• Check that generated code has been regenerated if protos changed

Local Development

CLI Development

For working on the Riven CLI itself:

cd ~/Desktop/riven-private/riven-cli
yarn install
yarn dev

This starts the CLI in development mode with hot reloading.

Frontend Development

For the platform UI, use the dev overlay mode which runs locally against production data:

cd ~/Desktop/riven-private/riven-platform/apps/riven-platform-app
riven dev --port 3000

This sets a cookie on app.riven-ai.dev so the production app loads your local JS/CSS via a Service Worker, giving you HMR with real auth and APIs.

Backend Services

For backend service development:

cd ~/Desktop/riven-private/dev-center/services/<service-name>
yarn install
yarn dev

Services typically start on their configured port with hot reloading via tsx watch.

Next Steps

• Migrating Services — Full guide for onboarding a service to the platform.
• Troubleshooting — Common issues and solutions.
• CLI Reference — Full CLI command reference.