Developer Guide¶

Welcome to the Farm Developer Guide. This section provides comprehensive documentation for developers who want to contribute to Farm or deploy it in their environment.

Overview¶

Farm is a full-stack application consisting of a NestJS backend (API, database, queues, WebSockets) and a Next.js frontend (dashboard, catalog browser, monitoring). This guide is organized into shared topics and stack-specific sections.

Getting Started¶

If you are new to Farm development, start with the Development Setup guide to configure your environment.

What's New (Phase 51-54)¶

Recent improvements to the development workflow and Kubernetes deployment:

Database Seeding: Seed Job pattern for post-install data population (Phase 51)
Helm Test Hooks: Automated health checks for API, Web, and database connectivity in KinD and production (Phase 52-53)
Migration Improvements: Refined pre-install hook weights and migration-config/secret handling (Phase 51-53)
Security Context: Fixed runAsUser numeric UIDs for container image compatibility (Phase 52-53)

See the Backend Developer Guide for implementation details.

Backend¶

The Backend Developer Guide covers the NestJS API server:

Topic	Description
Architecture	Module structure, request flow, data storage, and caching
Plugin System	Extending Farm with metadata-driven plugins
Testing	Unit tests with Jest, E2E tests, coverage thresholds
Observability	Prometheus metrics, Grafana dashboards, OpenTelemetry tracing
WebSockets	Real-time event streaming via Socket.IO
Queues	Background job processing with BullMQ and Redis
Email	Transactional email with SMTP and Handlebars templates

Infrastructure and Deployment¶

Topic	Description
Helm Chart Development	Maintaining and developing the Farm Helm Chart for Kubernetes deployment

Frontend¶

The Frontend Developer Guide covers the Next.js web application:

Topic	Description
Architecture	Project structure, routing, API integration, and design decisions
Testing	Vitest setup, writing component tests, and coverage

Shared Topics¶

Topic	Description
Development Setup	Prerequisites, installation, Docker, and environment variables
Contributing	Contribution workflow, code style, and pull request guidelines
Test Users	Seed personas, credentials, and recipes for testing roles, tenancy, and team scopes
System Design	High-level system architecture, data models, and API design
Security Testing	SAST, DAST, secret scanning, container CVE scanning, and accessibility testing

Technology Stack¶

Layer	Technology
Backend Framework	NestJS 11 (TypeScript)
Frontend Framework	Next.js 16 (React 19)
Database	PostgreSQL (SQLite for tests)
Cache	Redis (in-memory fallback)
Queue	BullMQ with Redis
UI Components	Shadcn/ui + Tailwind CSS v4
Backend Tests	Jest (unit + E2E)
Frontend Tests	Vitest + React Testing Library
Observability	Prometheus, Grafana, OpenTelemetry, Tempo
Containerization	Docker + Docker Compose

Quick Reference¶

# Full stack (Docker)
make up-all

# Backend only
make up-docker

# Run all checks
make check          # Backend + Frontend
make check-back     # Backend only (fmt, lint, test, e2e)
make check-front    # Frontend only (lint, build, test)

# Seed sample data
make seed