developer

Developer Guide

Welcome to the Ambient Code Platform developer guide! This section covers everything you need to contribute to the project.

🏁 Getting Started

Prerequisites

• Go 1.24+ (backend/operator)
• Node.js 20+ (frontend)
• Python 3.11+ (runners)
• Podman or Docker
• kubectl or oc CLI

Quick Start

1. Clone the repository:

   git clone https://github.com/ambient-code/vTeam.git
   cd vTeam

2. Set up local environment with Kind (recommended):

   make kind-up
   # Access at http://localhost:8080

   Full guide: Kind Development

   Alternatives: Minikube (older) • CRC (OpenShift-specific) • Comparison

3. Make your changes and test:

   make test
   make lint

4. Submit a Pull Request

📖 Developer Documentation

Local Development

• Local Development Guide - Choose your approach
  • Kind - Recommended (fast, matches CI/CD)
  • Minikube - Older alternative (still supported)
  • CRC - OpenShift-specific features only
  • Hybrid - Run components locally for debugging

Code Standards

• Code Standards - Comprehensive development standards
  • Backend & Operator standards (Go)
  • Frontend standards (TypeScript/React)
  • Security patterns
  • Error handling

Component Development

Each component has detailed development documentation:

• Frontend README - Next.js development
• Backend README - Go API development
• Operator README - Controller development
• Runner README - Python runner

Testing

• Testing Guide - Comprehensive test documentation
  • E2E Tests - Cypress end-to-end testing
  • Backend tests - Unit, contract, integration tests
  • Frontend tests - Component and E2E testing

🏗️ Architecture

Architecture Documentation

• System design and component interactions
• Architectural Decision Records (ADRs)
• System diagrams

Key Concepts:

• Custom Resource Definitions (AgenticSession, ProjectSettings, RFEWorkflow)
• Operator reconciliation patterns
• Multi-tenant namespace isolation
• User token authentication

🔧 Development Workflow

1. Create Feature Branch

git checkout -b feature/your-feature-name

2. Make Changes

Follow the established patterns in CLAUDE.md

3. Test Locally

# Run linters
make lint

# Run tests
make test

# Test locally
make local-up

4. Submit PR

git push origin feature/your-feature-name
# Create PR on GitHub

See CONTRIBUTING.md for full workflow details.

🛠️ Common Development Commands

Build

make build-all              # Build all components
make build-frontend         # Build frontend only
make build-backend          # Build backend only

Local Development

make local-up               # Start local environment
make local-status           # Check status
make local-logs             # View logs
make local-down             # Stop environment

Testing

make test                   # Run all tests
make test-e2e               # Run E2E tests
make lint                   # Run linters

Code Quality

# Go code
cd components/backend
gofmt -w .
go vet ./...
golangci-lint run

# Frontend code
cd components/frontend
npm run lint
npm run build

🎯 Where to Start

First-Time Contributors

1. Read CONTRIBUTING.md
2. Set up local environment with QUICK_START.md
3. Pick a "good first issue" from GitHub
4. Join the discussion in GitHub Discussions

Experienced Developers

1. Review Architecture Documentation
2. Read Architectural Decision Records
3. Choose appropriate Local Development approach
4. Check out component-specific READMEs

📚 Additional Resources

• API Reference - REST API documentation
• Tools - Optional development tools (Amber)
• Agent Personas - Multi-agent collaboration agents
• Troubleshooting - Common issues and solutions

🆘 Getting Help

• Questions? → GitHub Discussions
• Found a bug? → Report an Issue
• Want to chat? → Check project communication channels