Skip to content
Polo docs

Repository layout

Polo is one repository with four parts that run as separate processes: a browser app, a TypeScript control plane, a Python agent runtime, and Python tool packages that also run as customer runners. This page is the map. For how the parts work together, read Architecture.

The tree

Section titled “The tree”
polo/
  api/                  NestJS control plane (TypeScript)
    src/main.ts         the HTTP API process
    src/relay.ts        outbox relay: delivers stored events to Temporal
    src/scheduler.ts    schedules and uptime probes
    src/*-watch.ts      small polling workers (calendar, Gmail intake, follow-through)
    src/knowledge-indexer.ts
    src/modules/        one folder per product module
    src/platform/       config, database, HTTP, security, telemetry, Temporal client
    test/               acceptance tests, one folder per module, plus support/ fixtures
    Dockerfile          control-plane image
  runtime/              Python supervisor and agent runtime on Temporal (python -m runtime)
  tools/                everything an agent can use, one package per domain
    common/             operation adapters shared by the runtime and the runners
    workspace/          offline sandbox, source archives, skills, model harness
    terraform/ postgres/ kubernetes/ containers/
    aws/ azure/ gcp/ cloudformation/
  ui/                   browser app: plain HTML, CSS and ES modules, served by the API
    features/           one module per page or panel (product-*.js)
    shared/             API client, session, DOM helpers, shared state words
    cli/                the plungo command line, served at /cli/
  tests/                Python tests: runtime, runners, skills
    browser/            Playwright acceptance scripts
    fixtures/           cases shared between the Python and TypeScript sides
  scripts/
    local_product.py    the local launcher (init, serve, subscription)
    ops/                backup, restore, restore drill, load test, alert rules
  deploy/
    compose/            single-host Compose stack
    helm/polo/          Helm chart
    docker/             image entrypoints
  cmd/polo/             Go program that enrolls a computer with Plungo
  toolchain/            pinned Terraform toolchain for the sandbox image
  docs/                 CAPABILITIES, DEPLOYMENT, OPERATIONS, PILOT, SECURITY
  docs-site/            this documentation site (Astro Starlight)
  runtime.Dockerfile    runtime worker image
  tools.Dockerfile      customer-runner image
  engineering.Dockerfile  offline sandbox toolchain image
  pyproject.toml, uv.lock   Python project and locked dependencies
  ARCHITECTURE.md       the design record
  IMPLEMENTATION.md     dated ledger of what is built and verified
  idea.md               the product brief

Inside the control plane

Section titled “Inside the control plane”

Every folder under api/src/modules/ is one module with the same four layers:

modules/operations/
  http/             controllers and request parsing
  application/      services, command contracts (Zod), ports
  domain/           framework-free rules and types
  infrastructure/   TypeORM entities, repositories, migrations, provider clients
  operations.module.ts   the composition root that wires concrete classes
  index.ts               the module's public surface

The modules in the repository today:

Module Holds
identity Accounts, sessions, SSO, workspaces, team members and roles
work Agents (Polo profiles), tasks, runs, agent specifications, questions, budgets and usage
operations Connections, operation requests, approvals, approval policy, pre-authorized actions, runners, the vault
intake Signed deliveries from chat, tickets and alert sources that open tasks
automation Schedules, uptime monitors, incidents and notifications
knowledge Documents, runbooks, embeddings, published skills and learned facts
artifacts, reports Stored artifacts in object storage and published reports
models Model connections and routes
mcp External MCP servers Polo calls: registration, catalog, grants, OAuth
mcp-server Polo’s own MCP server and member access tokens
cloud Cloud accounts, resource graph, AWS, Azure, Google Cloud and CloudFormation providers
repositories, pipelines GitHub repositories, pull requests and CI evidence
observability, network Metrics, logs, traces and network diagnostics
platform-catalog The service and environment catalog
calendar, gmail, google-chat, google-files, google-oauth, slack-install, ticketing, clickup Collaboration integrations

There is no shared migrations/ folder. Each module keeps its own *.migration.ts files, and api/src/platform/database/registry.ts lists every entity and migration in order. npm run migrate applies them.

Inside the runtime

Section titled “Inside the runtime”
File Holds
runtime/__main__.py Starts the Temporal worker
runtime/workflows.py CaseWorkflow and AgentWorkflow: deterministic orchestration only
runtime/contracts.py Workflow and activity names, payload dataclasses, bounds
runtime/activities.py RuntimeActivities: claim, plan, delegate, step, review, finish
runtime/models.py Pydantic types for specs, plans and decisions; PydanticDecider
runtime/control_plane.py WorkCommands, the HTTP client for the control plane
runtime/operation_tools.py NATIVE_TOOLS, the typed arguments of every registered operation
runtime/tools.py SandboxTools: workspace read, write and registered checks
runtime/*_tools.py Typed arguments for cloud, CI, pipeline, knowledge, observability and report tools

Dependency rules

Section titled “Dependency rules”

These rules are enforced, not only written down. api/test/architecture/module-boundaries.test.ts parses every source file under api/src/modules/ and fails the build when one breaks them.

  • Domain code is framework-free. Files in domain/ import no NestJS, TypeORM, Temporal, provider SDK or environment configuration.
  • Application code depends on ports. Services talk to storage and providers through interfaces in application/ports.ts; the test allows only a short list of packages there, such as zod and node:crypto.
  • Controllers do no SQL and no agent work. SQL packages and SQL-looking strings are allowed only in infrastructure/.
  • Modules import each other through index.ts. A module never reaches into another module’s repositories or entities.
  • platform/security/contracts.ts holds types only, so any layer may import it.

Across process boundaries the rules are simpler:

  • runtime/ never opens a database connection. It calls the control plane over HTTP with a worker key and a run claim.
  • tools/common/ is imported by both runtime/ and the runner packages. Runner packages do not import runtime/.
  • ui/ talks only to the API’s HTTP routes. The API serves ui/ from an in-memory snapshot, so UI edits need an API restart.

Where to go next

Section titled “Where to go next”