Development¶
Guidelines for developers working on the platform, organized by intent: get productive, follow our standards, or learn the theory.
Getting Started¶
New to the project? Start here.
- Environment Setup — Local environment, dependencies, and tooling
- Workflows — Git branching, code review, CI/CD, and release process
Tooling & Processes¶
Tools and workflows that support daily development.
| Section | Description |
|---|---|
| Issue Tracking | YouTrack projects, fields, workflows, and writing good issues |
| AI-Assisted Development | Claude Code setup, daily workflows, skills, and agent teams |
| Shell & CLI | Daily commands, Docker, debugging, scripts, and productivity |
| CI/CD | GitHub Actions, build/test pipelines, deployment, and environments |
Engineering Standards¶
How we write and ship code across the stack.
| Section | Description |
|---|---|
| Backend | Python / FastAPI architecture, patterns, and reliability |
| Frontend | TypeScript / React / Next.js standards, patterns, and frameworks |
| Database | PostgreSQL migrations, connection management, and operational patterns |
| API Design | OpenAPI, versioning, error contracts, and documentation |
| Testing | Backend and frontend testing strategies |
| Security | Authentication, authorization, secrets, input validation, OWASP |
| Monitoring | Logging, metrics, tracing, and alerting |
Cookbook¶
Step-by-step recipes for common extension points.
| Recipe | What You'll Build |
|---|---|
| Add a Generation Strategy | New strategy in the generation pipeline |
| Add a Task Type | New compute task from model to dispatch map |
| Add an AI Provider | New provider processor with queue routing |
| Concurrency Recipes | Common concurrent and parallel task patterns |
Deep Dives¶
Theory, internals, and advanced patterns for when you need to go deeper.
| Section | Description |
|---|---|
| Concurrency | Processes vs threads, Python GIL, asyncio, event loop, worker pools |
| Database Internals | SQL fundamentals, query performance, indexing, transactions, backup |
| Performance | Profiling, load testing, benchmarking, optimization patterns |
| Advanced Patterns | Real-time features, server actions, streaming, event-driven, feature flags |
Key Principles¶
- Consistency Over Innovation — Follow existing patterns unless there's a compelling reason to change
- Test-Driven Development — Write tests while implementing, not after
- Atomic Implementation — Break features into small, testable tasks
- Pattern-First — New features follow existing patterns; AI agents are guided by referencing existing implementations
Recommended Reading Paths¶
| Goal | Path |
|---|---|
| New backend developer | Getting Started → Standards/Backend → Deep Dives/Database |
| New frontend developer | Getting Started → Standards/Frontend → Deep Dives/Advanced |
| Building a new feature | Cookbook → Standards (relevant stack) → Deep Dives as needed |
| Setting up AI tools | Tooling/AI-Assisted → Getting Started |