| name | rask-architecture |
| description | Where new code belongs in the rask workspace: the language-pure planes (Python `packages/` + `services/`, the `frontend/` bun+turbo root, sealed `runners/`) and the entrypoint contract (`make_service_app` + injectable lifespan). Use when adding, moving or deleting a workspace member, service, zone or deployable; editing a `pyproject.toml`, the root `uv.lock`, or a uv/bun workspace glob; wiring a service entrypoint; or when newly added code won't resolve — ModuleNotFoundError, a `uv sync` workspace error, or a package `bun install` silently skipped. |
rask architecture (workspace planes + composition)
The single most rask-specific thing to get right: which plane a package lives in, and how entrypoints compose packages. Get this wrong and uv/bun resolution breaks (loudly for uv, silently for bun) or you smear a domain across layers. Defers Python idioms to writing-python, FastAPI routing to fastapi, container builds to dockerfile.
There is no projects/ layer. The Polylith-style projects/<name> composition stubs were removed (2026-07). Deployables are ordinary workspace members built by .docker/<name>.dockerfile running uv sync --frozen --package <name> against the root uv.lock. Never recreate per-deployable pyprojects or per-deployable locks.
When to use
- Adding, moving, or deleting a workspace member (
packages/*, services/*, or anything under frontend/).
- Wiring a new HTTP service entrypoint or editing one.
- Editing any
pyproject.toml members/dependencies, or frontend/package.json workspaces.
- "ModuleNotFoundError" / uv won't resolve a first-party import after you added code.
- Deciding where new code belongs: reusable lib, runnable component, or deployable.
The planes — one language per plane
The tree is split by language first, then by layer. Each globbed directory is single-language; that is what makes the globs safe (see the invariants).
| Plane | Path | Rule | Has entrypoints? |
|---|
| Python packages | packages/<name> | reusable Python libraries (ray-cluster-env is deps-only: it NAMES the Ray images' environment and ships no code) | No entrypoints — the one CLI exception (ratch) died with its package at the 2026-08-28 dissolution |
| Python services | services/<name> | runnable Python: HTTP services | Yes |
| sealed runners | runners/<name> | model environments with their own pyproject.toml — and their own uv.lock only where they build an image (assist, dummy, htr); the offline Ray Data runners ship a pyproject alone and let Ray install the env on workers via runtime_env. Matched by no workspace glob | Yes (Ray entrypoints) |
| JS/TS frontend | frontend/ | its own bun + turbo workspace root (own package.json, bun.lock, turbo.json, knip.json, .oxlintrc.json, .oxfmtrc.json, patches/, assets/) | — |
| ↳ zones | frontend/microfrontends/<zone> | the 7 SvelteKit MFE apps | Yes |
| ↳ JS libraries | frontend/packages/<name> | reusable TS/Svelte libraries | No |
| scripts | scripts/ | ALL dev/ops scripts, shell and python, flat | one-shot, not a workspace member |
Current Python packages: lineage-kit, ray-cluster-env (deps-only), ray-kit, service-kit, storage, validate. (ratch was DISSOLVED 2026-08-28 — open_ray-kernel.md; tracker was DELETED 2026-08-30 — a per-file transfer ledger that never found a consumer here, its job done by JetStream WORK_QUEUE retention plus Dapr Workflow's durable state; htr is not a package — it is runners/htr, sealed and outside every glob.)
Current Python services (13): gateway, compute, controlplane, ingest, flows, notifications — plus the lance plane (catalog, lineage, medallion, maintenance, viewer, search, annotator). (notifications is the per-subject inbox behind the bell, :8850, app-id notifications — see rask-services-fleet.) (compaction was renamed maintenance in 06cc7579 — it compacts, optimizes indices, cleans up old versions and reconciles cross-store drift, so it is named for all four, not one. core/core_api/search_api/volumes_api died in the R6/R20 media wave.)
Current sealed runners (9): asr, assist, diarize, dummy, htr, insid3, kg, topics, voiceprint. (dummy is the GPU-free lane prover — real CDF read → merge_insert → fragment commit, no model download; insid3 is pinned to python 3.10.)
Current JS packages: api, config, dockview, engine, explorer-api, flow, labeling, , — see .
Current zones (7, verified against 2026-08-09): (catch-all, base ), , , , , , — each based at a bare . (on train's port 5178); a leftover on a dev host is untracked build residue, not a zone. // are ; and are routes .
Current deployables (each = a workspace member + a ): , (R22 — on every surface), , , , , — plus the one parametrized built per zone (images tagged ), (the Ray head/Serve image) and , which is ONE image for lance services (, , ×2 apps, , , , ) run with different commands. NB 's is still only — has a dockerfile and a chart Deployment () but is not in that build loop yet.
The composition seam: three app factories, one per plane
service_kit.make_service_app(*, title, routers, proxy_router=None, lifespan=None) builds the FastAPI app with shared config/handlers/middleware. The lifespan is injectable: stateless services get the minimal default_lifespan (settings only); stateful ones pass a LifespanFactory (Lance/Ray/S3). Routers mount under settings.api_prefix; proxy_router mounts at root.
⚠️ THREE FACTORIES ARE SANCTIONED — know which plane you are in. This section used to say two
layouts, and that the seven non-fleet services "construct FastAPI(...) directly with bespoke
lifespans"; that was true and is not any more. Twelve of the thirteen services now come out of a
factory, and which one is decided by the plane, not by taste:
| Plane | Factory | Services | Routers mount |
|---|
| fleet | service_kit.make_service_app | compute, controlplane, flows, ingest, notifications | under settings.api_prefix |
| media | service_kit.media.app.build_media_app | viewer, search, annotator | at the root; MediaSettings; CORS exposes the Range headers |
| lance | service_kit.lance_app.build_lance_service_app | catalog, lineage, medallion ×2 apps, maintenance | at the root; each service's own core/config.py::get_settings() |
gateway is in none of them — it builds FastAPI(...) itself, because it is a proxy, not a router
host. The media three also share ONE lifespan (service_kit.media.lifespan.make_media_lifespan),
with setup/teardown hooks for what is genuinely per-service (the annotator's actor plane).
The non-fleet services keep the fastapi skill's api/v1/endpoints/ + core/ + services/ layout
rather than the fleet's flat-module layout — that half of the old paragraph still holds. What changed
is the ENTRYPOINT: a main.py that opens its own app = FastAPI(...) is now the exception to
justify, not the norm (open_python-audit DUP-12 counted eight of them repeating one boot, and the
copies had drifted — the medallion mover had lost its request-id layer entirely).
A thin fleet-layout entrypoint is ~20 lines — import routers + a lifespan from the domain package, call the factory. compute/__init__.py:
from compute import health, proxy, routes
from compute.lifespan import make_lifespan
from service_kit import make_service_app
app = make_service_app(
title="compute",
routers=[health.router, routes.router],
proxy_router=proxy.router,
lifespan=make_lifespan,
)
The core husk is GONE (R6/R20, 2026-07-28)
services/core + services/core_api (the post-P7a transitional husk) are deleted, with search_api and volumes_api. Their capabilities live in the explorer plane: the S3 object browser is the viewer's objects.py endpoints (/api/explorer/object*); lines/EAD FTS re-land as catalog-governed Lance tables behind /api/explorer/search (docs/architecture/lance-ns-merge.md R6). Do not resurrect them.
Hard invariants (the gotchas)
- Workspace membership is globbed — and that is only safe because every globbed dir is single-language. Root
pyproject.toml has [tool.uv.workspace] members = ["packages/*", "services/*"]; frontend/package.json has workspaces = ["microfrontends/*", "packages/*"] (paths relative to frontend/). Drop a directory in the right plane and it is a member — no manifest edit. The safety condition is the language purity, and the two toolchains fail asymmetrically when it breaks: a dir under a uv glob without a pyproject.toml is a hard error (Workspace member … is missing a pyproject.toml), fixable only by an exclude list (enumeration by another name); a dir under a bun glob without a package.json is SILENTLY skipped — bun prints "Done!" and the package is simply never installed, built, linted or tested, and nothing says so. So: never put a JS package under root packages//services/, and never put a Python package under frontend/. (The root manifest also notes runners/* is deliberately matched by no glob — sealed model envs whose heavy pins must never enter the fleet's resolution.) See references/adding-a-package.md.
- One lock. The root
uv.lock is the only Python lockfile — dev, tests, and every fleet docker image resolve from it (uv sync --frozen --package <name>). The sealed runners/htr project carries its own lock and is invoked via uv run --project runners/htr runner (in-cluster the ray image ships the console script on PATH).
service-kit keeps a light base. Base deps are storage, fastapi, pydantic, pydantic-settings, python-dotenv, dapr>=1.18.1, and 8 OpenTelemetry packages — the SDK, the OTLP/HTTP exporter, and instrumentors for fastapi, httpx, logging, requests, grpc and aiohttp-client. The last three landed 2026-08-23: the fleet runs bare uvicorn with no opentelemetry-instrument launcher, so whatever setup_otel names is ALL the instrumentation it gets, and without grpc + aiohttp the app→sidecar hop carried no and every Dapr span rooted a new trace. The heavy Lance/Ray deps live behind the / / extras — keep them there. add , , or to the base: service-kit is shared by every service including the storeless ones ( via , ).
When to load each reference
| Need | Read |
|---|
Adding, moving or deleting a member or deployable — run its checklist to the end; step 4 (known-first-party) is the one that gets skipped | references/adding-a-package.md |
| The full service fleet, ports, and which package each entrypoint composes | references/service-fleet.md |
Sibling skills
rask-services-fleet (the gateway + per-service routing) · rask-frontend (zones, data, gates) · rask-styling (@rask/ui) · rask-lance-catalog (the catalog, governance, maintenance).
A runner's internals are deliberately undocumented here: each runners/<workload> is sealed and owns its
own pipeline, models and GPU packing. There is no per-workload skill — one would make that modality look
privileged, which is the opposite of how this platform is built.
