Platform Overview

# Platform Overview

The Sprinter Platform is a structured intelligence engine. It captures, connects, scores, and enriches structured data through a combination of human input and autonomous AI agents. The first product built on it is Amble, a PE portfolio intelligence tool, but the platform itself is domain-agnostic by design.

## What it does

The platform provides five interconnected capabilities:

1. **Entity graph** -- Any structured data type (opportunities, companies, contacts, projects) lives as an entity with typed fields, tags, relationships, and metadata. Entities form a navigable graph of connections.
2. **Multi-agent AI** -- A registry of AI agents with distinct personas, tool access, and permission scopes. Agents work in supervised mode (chat with a user) or autonomous mode through scheduled actions, session execution, and field-population runs.
3. **Agentic field population** -- Per-field AI work where each field has its own agent loop, dependencies, source policy, and response review flow. Agents use tools to search the web, read documents, and cross-reference connected entities.
4. **Config-driven views** -- Blocks (20 types) compose into views (list, detail, workspace). Views are stored in the database and can be authored by agents at runtime. No code deployment required to change how data is displayed.
5. **Actions and sessions** -- Visible actions define work; sessions and session events execute and trace it. Parent/child actions coordinate multi-step processes across agents and humans with claim/resume semantics, human-in-the-loop wait states, and automatic retry.

## Who it serves

The platform targets data-intensive organizations that need structured intelligence workflows:

- **PE and venture capital firms** -- Portfolio tracking, deal pipeline, operational scoring, AI-enriched due diligence
- **Consulting firms** -- Client engagement tracking, AI readiness assessments, ROI analysis
- **Any organization** that manages complex, relationship-heavy data and wants AI agents to do the research and enrichment work while humans review and approve

The design system reflects this audience: enterprise-grade, light mode, zero-chroma neutral grays, deep navy primary. Clean and trustworthy, not flashy.

## The reusability model

Reusability is the number one architectural goal. To create a new product on the Sprinter Platform:

1. Fork the repository
2. Replace `features/custom/` -- this is the only directory that contains product-specific code
3. Seed different entity types in the database
4. Update branding (CSS variables in the theme, logo text in `app-sidebar.tsx`)
5. Deploy

Everything outside `features/custom/` is platform code that ships unchanged across all products. The `features/custom/` directory contains:

- **Custom components** -- Product-specific entity type UI (cards, detail views)
- **Custom tools** -- Domain-specific calculators and utilities (ROI calculator, readiness assessment)
- **Custom lib** -- Shared product utilities (formatting, constants)
- **Custom server** -- Product-specific server actions (dashboard data aggregation)

### The boundary rule

Platform code must never import from `features/custom/` or reference product-specific slugs. Custom code can import from platform features freely. Entity types, schemas, and field configurations are all database-driven -- the platform renders them generically. Custom components are optional overrides registered via runtime registries.

## Major systems at a glance

| System | Directory | What it does |
|---|---|---|
| Entity system | `features/entities/` | CRUD, views (bento/list/grid/kanban), scoring, extraction, tags, import/export |
| Agent system | `features/agents/` | Agent registry, delegation, heartbeat scheduling, config versioning, org chart |
| Tool system | `features/tools/` | Registry, execution engine, AI bridge, generic UI, collaborative sessions |
| Block system | `features/blocks/` | 20 block types, BlockGrid layout, bridge functions from entities/tools/chat |
| View system | `features/views/` | Config-driven layouts (list/detail/workspace), regions, tabs, AI authoring |
| Chat system | `features/chat/` | Multi-agent conversations, persistence, history, agent selection |
| Workflow engine | `features/inngest/` | Background jobs: extraction, heartbeat, webhooks, document processing, cascade |
| Navigation | `features/navigation/` | Sidebar customization: sections, items, dynamic sources, tenant/user overrides |
| Documents | `features/documents/` | Upload, processing, chunking, signed URLs, hybrid search |
| Multi-tenant | `features/tenant/` | Tenant isolation, switching, member management, URL-based routing |
| Auth and RBAC | `features/tenant/auth.ts` | JWT auth, 63 granular permissions, role-based tool gating |
| Capture | `features/capture/` | Natural language to structured entity creation |
| Context | `features/context/` | Tenant-level corrections and learnings injected into agent prompts |
| Analytics | `features/analytics/` | Fire-and-forget event tracking |
| API keys | `features/api-keys/` | Generate, validate, revoke, scope enforcement |
| Comments | `features/comments/` | Threaded comments on entities with activity logging |
| Charts | `features/charts/` | Reusable Recharts wrappers (radar, bubble) |

## Pages

| Route | Purpose |
|---|---|
| `/dashboard` | KPIs, charts, top records, recent activity |
| `/insights` | AI transformation dashboard (pipeline, category, value) |
| `/chat` | Multi-agent chat with history sidebar |
| `/feed` | Personalized entity feed (ranked, filterable) |
| `/activity` | Activity timeline |
| `/graph` | Entity relationship graph visualization |
| `/documents` | Document library (upload, search, download) |
| `/[typeSlug]` | Entity list (table/grid/kanban) with views, search, sort, filter |
| `/[typeSlug]/[id]` | Entity detail (bento grid or configured view, inline editing, scoring) |
| `/view/[id]` | Standalone view page (shareable, forkable) |
| `/tools` | Tool library and individual tool pages |
| `/admin` | Tenant, members, roles, entity types, agents, jobs, costs, webhooks, API keys |
| `/settings` | Account info, workspace stats |
| `/t/[tenantSlug]/...` | Tenant-scoped URLs (middleware rewrites) |

## Tech stack

| Layer | Technology |
|---|---|
| Framework | Next.js 16.1.6 (App Router, Turbopack) |
| Language | TypeScript strict, Zod 4 for runtime validation |
| UI | shadcn/ui + Tailwind CSS v4 (60+ components) |
| Database | Supabase (Postgres, Auth, RLS, Storage, Realtime) |
| AI | AI SDK v7 (`streamText`, `convertToModelMessages`, `DefaultChatTransport`) |
| Client state | React Query (`@tanstack/react-query`) |
| Charts | Recharts |
| Graph | @xyflow/react |
| Background jobs | Inngest |
| Monitoring | Sentry (`@sentry/nextjs@10`) |
| Testing | Vitest (unit/integration), Playwright (e2e/smoke) |

## Six architecture primitives

The entire platform can be understood through six primitives:

1. **Record** -- An entity with typed fields, tags, relationships, and metadata. The atom of structured data.
2. **Agent** -- An AI persona with a system prompt, model, tool access, and permission scope. Can work supervised (chat) or autonomously (heartbeat).
3. **Action** -- A tool or extraction step that an agent executes. Tools are reusable by humans (form UI) and agents (AI SDK tools).
4. **Work** -- A workflow run coordinating multiple agents and humans through a DAG of nodes. Supports claim/resume and human-in-the-loop.
5. **Message** -- A chat message with AI SDK v7 parts (text, tool calls, tool results). The unit of human-agent communication.
6. **Context** -- Tenant-level corrections and learnings that improve all agents over time. One correction teaches every agent in the workspace.