The repository is organized by product ownership rather than implementation language. A contributor should be able to distinguish customer interfaces, platform services, infrastructure, examples, and test evidence without knowing the codebase first.
Find the component you need
| Directory | Ownership |
|---|---|
apps/ |
User-facing applications. apps/console serves the tenant, operator, status, Access, and public landing surfaces. |
services/ |
Platform control services: control plane, identity, quotas, and certificate management. |
services/resources/ |
Providers for tenant capabilities such as storage, databases, queues, Images, Models, and Durable Objects. |
infra/ansible/ |
Shared Ubuntu provisioning, inventory, roles, and service configuration. |
infra/lima/ |
Compact and multi-node local VM definitions. |
examples/ |
Applications deployed through the same Wrangler and platform APIs available to users. |
tests/performance/ |
Cross-service load profiles, fixtures, and contract tests. |
tools/ |
Repository automation behind the root Makefile. |
docs/ |
Product, application, operations, and architecture guides. |
artifacts/ |
Ignored, retained outputs from benchmarks and browser tests. |
Package-local unit and property tests stay beside the package they verify.
Cross-service tests belong under tests/. Infrastructure is responsible for
installing platform code, while application deployment remains a Wrangler
workflow.
Understand local state
The repository uses two ignored state roots with different lifecycles:
.cache/is disposable. It contains virtual environments, downloaded dependencies, transient locks, and build caches..local/is durable operator state. It contains local HTTPS trust metadata, generated service credentials, and the encrypted Latitude Ansible Vault.
Deleting .cache/ should only make the next command slower. Do not delete
.local/ casually: its contents may be required to administer an existing
deployment or remove a locally trusted certificate authority cleanly.
Validate a change
Use the affected package’s native test or lint command while iterating, then run the repository gate:
make checkThe gate includes infrastructure validation, dependency audits, package tests,
complexity and coupling checks, example builds, and diagram validation. Changes
that need a live platform should begin with make status; do not assume a local
VM is running or current. Use make site to converge it, then choose a live
suite with make test SUITE=<suite>. The integration inventory is listed by
python3 tests/integration/run.py --list.