Thin by design
This backend is a host layer around @lnittman/convex-agents, not a second app-specific backend implementation.
The backend in this repo is intentionally thin. It mounts the shared component, exposes wrapper functions for the dashboard, and provides host-level sync and HTTP surfaces.
Key architecture facts
convex.config.tsmounts@lnittman/convex-agentsschema.tsdefines no host-local tableshttp.tsmounts Agentation-compatible HTTP routesagentSystem/**exposes dashboard-friendly wrappers over the mounted componentsync/**exposes host mutations for upserting local state into Convex
Important files
| File | Purpose |
|---|---|
packages/backend/convex/convex.config.ts | Mount shared component |
packages/backend/convex/schema.ts | Empty host schema by design |
packages/backend/convex/http.ts | Agentation HTTP surface |
packages/backend/convex/host.ts | Host identity query |
packages/backend/convex/agentSystem/activity.ts | Home feed, stats, and time series |
packages/backend/convex/agentSystem/dispatch.ts | Queue web work for local execution |
packages/backend/convex/agentSystem/projects.ts | Project list/create wrappers |
packages/backend/convex/agentSystem/skills.ts | Skills list wrapper |
packages/backend/convex/agentSystem/previews.ts | Previews list wrapper |
packages/backend/convex/agentSystem/annotations.ts | Annotation list/upsert wrappers |
packages/backend/convex/agentSystem/threads.ts | Thread create/list/get wrappers |
packages/backend/convex/agentSystem/traceEvents.ts | Timeline event access |
Why the host layer stays thin
This repo is meant to be the canonical home for the shared agents ecosystem, not a forked app-specific backend that duplicates component logic. The dashboard reads through wrapper functions that shape the shared component into product-specific queries.
Practical implication
Shared nouns
Put reusable model changes in @lnittman/convex-agents.
Host wrappers
Shape the shared component for product needs in packages/backend/convex/agentSystem/**.
UI consumption
Consume the resulting queries and mutations from apps/app.