Developer Documentation¶

This documentation is for engineers, technical partners, and self-host operators working directly from the validibot repository. If you're looking for day-to-day product usage guidance, see the User Guide instead.

Deployment pages in this repo are customer-facing for self-hosted installs. Daniel-specific validibot-cloud and GCP operator workflows belong in validibot-project.

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. Run Validibot Locally — First-time local setup for self-hosting and evaluation

Architecture¶

Understand how the system is built:

• Workflow Engine — How ValidationRunService orchestrates steps
• Step Processor — The processor pattern for validator execution
• Plugin Architecture — The shared registration and sync model for validators and actions
• 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
• Signals — Concepts and terminology for declared signals and custom data paths
• Signals Tutorial Example — End-to-end walkthrough of signal contracts, step bindings, derivations, and runtime traces
• Results — Findings, artifacts, and summaries
• Users & Roles — Organization membership
• Deletions — How deletions are managed

Deployment¶

Deploy Validibot to production:

• Deployment Overview — Choose the right deployment target
• Run Validibot Locally — Quickest path to a running app
• Deploy with Docker Compose — Single-host self-hosting
• Deploy to GCP — Managed cloud deployment on Google Cloud
• Deploy to AWS — Current status and interim guidance
• Google Cloud Run Deep Dive — Full Cloud Run runbook
• Docker Compose Responsibility — Operator responsibilities for self-hosting
• 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.