Developer Documentation¶

This documentation is for developers working on Validibot itself. If you're looking to use Validibot as an end user, see the User Guide instead.

Getting Started¶

New to the codebase? Start here:

1. Platform Overview — What Validibot is and the problems it solves
2. How It Works — Technical walkthrough of the validation lifecycle
3. Quick Reference — Core concepts and basic usage patterns
4. Docker Setup — Run Validibot locally with Docker

Architecture¶

Understand how the system is built:

• Workflow Engine — How ValidationRunService orchestrates steps
• Step Processor — The processor pattern for validator execution
• Submission Modes — How API payload shapes are detected
• Settings Reference — Environment variables and feature flags
• Dashboard — Architecture and extension points for the dashboard module
• Related Libraries — How validibot_shared connects to this project
• Commercial Extensions — How Pro and Enterprise packages plug in

How-To Guides¶

Step-by-step instructions for common tasks:

• Using a Workflow via the API — Submit data programmatically
• Author Workflow Steps — Configure validation steps in the UI
• Configure Storage — Set up file storage backends
• Configure Scheduled Tasks — Set up background jobs
• Add a Form — Django Crispy Forms patterns
• Manage Organizations & Projects — Admin workflows

Data Model¶

The entities that make up Validibot:

• Data Model Overview — Core entities and relationships
• Projects — Organization-scoped namespaces
• Submissions — Content being validated
• Runs — Validation execution tracking
• Steps — Individual validation operations
• Results — Findings, artifacts, and summaries
• Users & Roles — Organization membership
• Deletions — How deletions are managed

Deployment¶

Deploy Validibot to production:

• Deployment Overview — Environments and release workflow
• Google Cloud — Deploy to Cloud Run
• Docker Compose — Docker Compose deployments
• Scheduled Jobs (GCP) — Cloud Scheduler setup
• Scheduled Tasks (Docker Compose) — Celery + Celery Beat
• Go-Live Checklist — Pre-launch tasks
• Important Notes — Common deployment gotchas

Integrations¶

• EnergyPlus Modal — Modal-backed EnergyPlus simulation runner

Testing¶

Run the test suite with uv run --group dev pytest. Integration and E2E tests have their own just recipes.

See Testing Overview for the full testing strategy, including when to use each test layer and detailed guides for integration, stress, and EnergyPlus E2E tests.