Architecture

Two-channel distribution, package map, and dependency graph for the Sprinter Platform.

Two-Channel Distribution

The Sprinter Platform ships through two independent channels:

npm Packages (logic layer)

Published to npm under the @sprinterai scope. These are versioned, typed TypeScript packages that contain all business logic, types, and runtime behavior.

@sprinterai/core      -- types, store interfaces, builders, extraction algorithms
@sprinterai/runtime   -- agent execution, tool registry, chat, workflows, evals
@sprinterai/supabase  -- Supabase clients, auth, persistence stores
@sprinterai/typespec  -- markdown DSL for entity type definitions

shadcn Registry (UI layer)

A shadcn-compatible component registry at /r/{name}.json. Components are installed directly into your project source, not consumed as npm dependencies.

npx shadcn@latest add https://ui.sprinterai.dev/r/entity-card.json

This separation means you can use the runtime packages without any UI, or use the UI blocks with a different runtime.

Package Map

sprinter-platform/
  packages/
    core/         @sprinterai/core       -- types, builders, extraction algorithms
    runtime/      @sprinterai/runtime    -- execution engine
    supabase/     @sprinterai/supabase   -- storage backend
    typespec/     @sprinterai/typespec   -- type specification DSL
  registry/                              -- shadcn block registry
  site/                                  -- this documentation site
  starters/                              -- project templates

Dependency Graph

@sprinterai/runtime
  depends on: @sprinterai/core, ai (v6)

@sprinterai/supabase
  depends on: @sprinterai/core, @supabase/ssr, @supabase/supabase-js

@sprinterai/typespec
  depends on: @sprinterai/core

@sprinterai/core
  depends on: zod

@sprinterai/core is the foundation. It has a single dependency (Zod) and defines all the types, store interfaces, and builder functions that the rest of the platform consumes.

@sprinterai/runtime is the execution engine. It depends on core for types and on AI SDK v6 for LLM integration. It provides agent resolution, tool execution, chat handling, workflow compilation, scoring, evals, and memory.

@sprinterai/supabase is the storage backend. It depends on core for store interfaces and implements them using Supabase. It also provides auth, tenant management, and realtime subscriptions.

Key Design Decisions

Store interfaces in core, implementations in backends

Core defines abstract store interfaces (EntityStore, AgentStore, ChatStore, etc.). The runtime package provides in-memory implementations for testing. The supabase package provides production implementations. This keeps the core package dependency-free and allows swapping backends.

Builders as the authoring API

Rather than constructing raw objects, developers use builder functions (defineEntityType, defineAgent, defineTool, defineModule, defineApp) that provide sensible defaults and return frozen objects. This provides a clean, discoverable API surface.

Modules as the composition unit

A SprinterModule bundles entity types, agents, and tools into a self-contained unit. An AppDefinition composes modules into a full application. This enables the fork-and-replace pattern: swap one module to create a different product.

Entity types are data-driven

Entity types live in the database, not in code. The defineEntityType builder is used for seeding. At runtime, the platform reads entity type schemas from the database and renders forms, cards, and detail views generically. Custom UI is optional.

Agents have a role_id just like users. When an agent executes tools, it is limited to the permissions granted by its role. In supervised mode (chat), the agent inherits the user's permissions. In autonomous mode (heartbeat), it uses its own role's permissions.

Data Flow

User/Agent Action
  -> Tool Execution (runtime)
    -> Store Interface (core)
      -> Supabase Store (supabase)
        -> Postgres + RLS

For agent execution:

Chat Message / Heartbeat Trigger
  -> Agent Resolution (find agent, build prompt, resolve tools)
    -> LLM Call (AI SDK v6 streamText/generateText)
      -> Tool Calls (resolved tool set, permission-gated)
        -> Store Operations (entity CRUD, response submission)
          -> Activity Log + Inngest Events

On this page