Developer guide

Clone the repository, build the Go services and the modeler, and run the check that matches your change. The Node.js SDK, the Python worker, and the Go worker client live in the same tree.

Requirements

• Git and Make.
• Go 1.25.12, or a compatible Go 1.25 toolchain.
• Node.js 20 or newer, and npm, for the modeler and the Node.js SDK.
• Python 3.10 or newer, if you work on the Python worker.
• Docker with Compose v2, when you run the local stack or integration tests.

Clone and install

git clone https://github.com/artificialflow/artificialflow.git
cd artificialflow
go mod download
npm --prefix frontend ci
npm --prefix clients/nodejs-sdk ci
pip install -e clients/python-sdk

Release v1.1.0 is the line this site documents. Development happens on main.

Build and run

make build-backend
make build-frontend
npm --prefix frontend run dev
make up-external-iam

Edit the issuer, client, and claim values in docker-compose.external-iam.yml, then make up-external-iam builds images from the checkout and starts Postgres, Elasticsearch, Kafka, Debezium, and the application. Published images use ARTIFICIALFLOW_IMAGE_TAG=v1.1.0 make up-external-iam-release, which overlays docker-compose.release.yml. The frontend dev server listens on port 5173. Database setup and local connector registration happen when the Compose stack starts.

Checks

Run the smallest check that covers the change, then the deeper one for that area.

go test ./backend/...
npm --prefix frontend test
npm --prefix clients/nodejs-sdk test
python -c "from artificialflow_worker import Worker"
make smoke-profiles
make validate-helm

make test-bpmn-matrix
make worker-conformance
make cqrs-e2e-smoke
make test-integration
make test-e2e
make test-security

Integration and end-to-end targets expect a running stack. The repository docs/QUALITY_GATES.md lists which checks belong to which kind of change.

Contributing

1. Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and docs/DEPENDENCY_POLICY.md.
2. Fork the repository and keep the change focused.
3. Keep domain, application, persistence, and interface boundaries separated.
4. Add tests and documentation when behavior or a contract changes.
5. Put the checks you ran in the pull request.

Report security issues to security@artificialflow.io or through GitHub private vulnerability reporting. Do not open a public issue for a vulnerability.