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.

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

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
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