Developer Guide

For people who want to run Loom from source, understand how it fits together or contribute a change.

This guide assumes you are comfortable with Python or TypeScript and a terminal. You do not need to be an expert in React, FastAPI or Polars.

Where to start

Goal	Start here
Set up a development environment	Getting Started
Understand how the pieces fit	Architecture Overview
Add a tool	Adding Tools
Add a file format	Adding Data Formats
Fix a bug or send a change	Contributing Workflow
Run the tests	Testing Philosophy
Build or release the app	Packaging and Releasing
Call the API	API Endpoints

The codebase in one paragraph

Loom is a monorepo. Studio (studio/) is a React app that runs in Electron, Tauri or a browser. Server (server/) is a FastAPI service that executes workflows with Polars. Hub (hub/) is a FastAPI and React platform, backed by PostgreSQL, for teams. Studio never touches your data. It sends workflow JSON to a Server and shows what comes back.

Python uses uv. JavaScript uses Bun. Both have lockfiles that CI enforces.

Why contribute

• You will use it. The best contributions come from users who hit a limit and fix it.
• Changes stay local. Most features touch one tool, one config panel or one endpoint.
• It stays open. The code is AGPL-3.0, and the CLA has legal safeguards for that.
• Reviews are public. Ask questions in issues and discussions so the answers help others.

Communication

• Bugs: GitHub Issues
• Ideas and questions: GitHub Discussions
• Security problems: see SECURITY.md. Do not open a public issue.

Principles

• Ship, then polish. Working software beats perfect plans.
• Test the bones. Core logic gets heavy testing. UI gets lighter testing.
• Explicit over magic. Behavior should be predictable and traceable.
• Every feature has a maintenance cost. Saying no is part of the job.
• Honest documentation. If something is broken, say so. If a decision was a trade-off, say why. See Known Issues and the Architectural Decisions.