Get Started

Architecture overview

Five peer product surfaces share one tenant-scoped control plane. Understanding that shape explains most of what the platform does and where your code fits.

This is the external architecture. The incremental migrations in migrations/ are the source of truth for the schema. full_schema.sql lags behind.

The control plane

Every request enters through FastAPI at /v1 behind auth and tenant policy. Tenancy is a bound execution context that follows the request into the store layer (bind_store_tenant), the retrieval path, and the agent runtime. It is not a header convention, and no query or tool dispatch can escape it.

React frontend (frontend/ :5173)
        │
        ▼
FastAPI /v1  ── auth + tenant policy (src/lace/auth)
        │
        ├── app framework ── LaceAppManifest, collections, routes, tools, agents, pipelines
        ├── execution ────── agent runtimes (in-process + external), pipeline orchestration, workers
        ├── knowledge ────── datasets, connectors, ingest, RAG, enterprise search, KG
        └── platform data ── Postgres + pgvector, object storage (MinIO/S3), event bus (NATS), Redis
                                │                  │
                                └──── reranker (services/reranker, GPU) ────┘

The five surfaces

Surface	What it is	Where it lives
Apps	Manifest-defined packages: routes, tools, agents, pipelines, data, UI, schedules, migrations.	`src/lace/apps`, `src/lace_app_sdk/manifest`, `src/lace_runtime`
Agents	Tool-using definitions with deployments and channels; real agentic loops in sidecars.	`src/lace/agent`, `src/lace_app_sdk/agents`
Pipelines	Versioned, typed workflow graphs with checkpoints, retries, idempotency, DLQ.	`src/lace/pipeline`
Knowledge	Datasets, connectors, ingest, retrieval, search, knowledge graph, extraction, schema packs.	`src/lace/domain`, `src/lace/connectors`
Assistant	Tenant-scoped copilot over the same APIs — OBO identity, operation catalog, context resolvers.	`src/lace/assistant`

App framework

An app is a LaceAppManifest plus providers. The manifest contains only data and has no import paths for handlers, so the platform can project it into catalog rows without executing app code. At activation, the sidecar imports the declared tool_modules / route_providers / agent_providers in the app's own process and registers handlers locally. The platform then invokes them over HTTP (lace_runtime.tool_host).

LaceAppManifest — manifest reference
AppDataCollectionSchema + AppDataService — data collections
@tool + AppToolDescriptor — tools
AgentDefinition + AppAgentProvider — agents
AppRouteProvider — routes & UI
AppPipelineProvider — pipelines

Execution

Agent runtime runs turns through a real agentic loop where the model chooses tools. Guardrails, hooks, loop guards, skills, and approval gates are host-registered. The manifest declares the agent and the runtime enforces the policy. Pipeline runtime checkpoints every step, so a crash resumes from the last completed step. Idempotency keys make retries safe, and work that cannot succeed goes to a dead-letter queue instead of disappearing.

Knowledge stack

Datasets are tenant-scoped containers over uploads and live connectors (SharePoint, Drive, OneDrive, Dropbox, Notion, Slack, email, S3, DBs, web). Each connector reports a capability manifest (incremental sync, deletes, permission reads) so the platform never assumes a lowest common denominator. Ingest parses, chunks, and embeds with stable document / block / span identity. Retrieval fuses lexical and vector legs with RRF, filters by source ACLs, and optionally reranks on GPU. Knowledge Graph is bitemporal and evidence-gated: schema packs are versioned executable contracts, extraction is candidate-first, identity is reversible, assertions supersede rather than erase.

Platform data

Postgres is the write store (with pgvector), NATS is the event bus, Redis is the cache/lock layer, object storage holds blobs and UI bundles. Services: postgres, minio, nats, redis (base compose) plus api (:8000), frontend (:5173), ingest-worker, chat-worker, reranker (dev overlay). Cloud is ECS Fargate in us-east-2; frontend on S3/CloudFront.

Request flow

Browser → FastAPI → auth + tenant binding → route handler or app sidecar (via /apps/<app_id>/api/*).
Data writes go through AppDataService → Postgres (JSONB collections) or blob store (content-addressed).
Tool calls are dispatched to the owning app's sidecar over HTTP, with trust tier and permissions checked before dispatch.
Retrieval and enterprise search fan out to catalog / document / KG legs, fuse, ACL-finalize, and return cited results.
Every hop emits structured logs and OpenTelemetry spans with per-call model attribution.

Next: deployment options or jump to install the SDK.