latitude-llm AGENTS.md

AGENTS.md

High-level guide for coding agents working in this repository.

Product scope

Multi-tenant LLM observability platform. The repo is a pnpm workspace orchestrated with Turbo.

At a glance: apps/* own transport (middleware, authn, mounting); @repo/operations owns the public API's operation contracts (validation, public schemas, routing to use-cases) shared by HTTP/MCP/SDK/CLI and in-process agent tools; packages/domain/* own business rules and ports; packages/platform/* implement infrastructure adapters; @repo/utils holds cross-cutting pure helpers. Telemetry and control data flow through Postgres, ClickHouse, Redis, and object storage, with organization-scoped access everywhere at the boundary.

Repo-wide conventions

• Organization-scoped Redis or cache keys must start with the organization prefix: org:${organizationId}:.... Put the org id first so tenancy is obvious and keyspaces stay consistently partitioned.
• Code comments are rare, and one line when they exist. Default to no comment — naming and structure should carry the meaning; a comment explaining what code does is a signal to rewrite the code, not to annotate it. Write a comment only for something the code cannot show: a trap (code that looks wrong, removable, or simplifiable but breaks something — ordering requirements, magic values, workarounds for framework/library quirks), a non-obvious external constraint, or contract docs where the file's existing convention documents every sibling (e.g. JSDoc on every method of a port). Never narrate the change you just made, restate what the next line does, paraphrase a well-named identifier, add section-header comments, or explain design rationale in the code — rationale belongs in the commit or PR description. When editing existing code, don't add comments describing your edit, and feel free to delete comments your change made stale or redundant. A comment describes the code as it stands, not the development process that produced it: never anchor one to transient context like a rollout phase, ticket id, or "new"/"now" framing (e.g. // Phase 2 (LAT-749): ...) — that reads as stale the moment the phase lands; state what the code does and put the ticket in the commit/PR. The only comments that may name a ticket are actionable TODO/FIXME markers for work not yet done.
• Never invoke tsc directly. Typechecking goes through tsgo via the package typecheck script — use pnpm --filter <pkg> typecheck for one package or pnpm typecheck for the whole workspace. tsc would diverge from CI.
• ClickHouse migrations must be created with pnpm --filter @platform/db-clickhouse ch:create <migration_name>. Do not create ClickHouse migration files manually.
• PR base branch follows the branch's origin. Branches forked from development (v2 work, default) PR into development; branches forked from latitude-v1 (v1 maintenance) PR into latitude-v1. Never start a branch from main without confirmation — if the working branch is based on main, or the user asks to branch from main, confirm with the user first. Detect an existing branch's base by testing ancestry in order: if git merge-base --is-ancestor origin/latitude-v1 HEAD is true → latitude-v1; else if git merge-base --is-ancestor origin/development HEAD is true → development; else the branch is likely based on main (or something unusual) — stop and confirm with the user before opening a PR. When the user asks to start a new branch, take the base from their wording (mentions of v1 → latitude-v1; otherwise default to development).
• Production deploys use the single-branch release-tag flow: development is trunk and deploys to staging by default; production is triggered only by pushing a vX.Y.Z tag that points at the latest origin/development commit. Before tagging a production release, update CHANGELOG.md with a human-readable diff of the code being pushed to production since the previous production deploy, focusing on the major aspects rather than every commit. Use scripts/release.sh [version] to fetch and tag the latest origin/development commit; without a version it bumps the latest vX.Y.Z tag to the next patch version, with --minor / --major available for larger bumps. Do not promote by merging development into main.
• Keep the product cleanly OSS and self-hostable. Shipped runtime dependencies must be permissively licensed (MIT/Apache-2.0/BSD/ISC) — no AGPL/SSPL/source-available code in the application bundle; audit a new dependency's license (and its transitive additions) before adding it. The self-host object store is SeaweedFS (Apache-2.0) — never reintroduce MinIO or any AGPL store as a bundled default. Keep every infra dependency isolatable and bring-your-own-able (dedicated schema/db/namespace/bucket; Redis keys namespaced under latitude:) so a self-hoster can swap any bundle for a managed instance. Rationale + full audit: dev-docs/licensing.md; self-host architecture: dev-docs/self-hosting.md.
• Private partner endpoints live under /v1/private/* and are plain Hono routes. They serve vetted, staff-registered partners, are authenticated by per-partner HMAC request signing (never a bearer token), and must stay off every generated surface — use a plain app.post(...), never app.openapi/createRoute, never defineOperation. Every pre-scope refusal returns an identical 401 {"error":"unauthorized"} so the surface can't be used to enumerate partner ids; only a scope failure gets a distinct 403. Details: dev-docs/partners.md.
• Two image registries, distinct jobs. Public self-host images go to Docker Hub latitudedata/<service> — env-neutral, multi-arch, for the six build targets (api, ingest, workers, workflows, web, migrations) — tagged to the release flow: :X.Y.Z + :latest on a release (git vX.Y.Z with the v stripped) are the stable tags self-hosters pin, :development is the trunk edge tag. GHCR (latitude-<env>-<service>, sha-tagged) stays Latitude's private own-deploy registry and is never the self-host source.