diff --git a/apps/web/src/app/docs/architecture/page.tsx b/apps/web/src/app/docs/architecture/page.tsx index aba94bf..aa9e73a 100644 --- a/apps/web/src/app/docs/architecture/page.tsx +++ b/apps/web/src/app/docs/architecture/page.tsx @@ -1,58 +1,57 @@ 'use client'; +import { Badge } from '@tpmjs/ui/Badge/Badge'; +import { Container } from '@tpmjs/ui/Container/Container'; import Link from 'next/link'; import { AppHeader } from '~/components/AppHeader'; -// Chip-style box component -function ChipBox({ +// Reusable box component for architecture diagrams +function ArchBox({ children, className = '', variant = 'default', }: { children: React.ReactNode; className?: string; - variant?: 'default' | 'accent' | 'highlight' | 'muted' | 'header'; + variant?: 'default' | 'primary' | 'muted' | 'header'; }) { const variants = { - default: 'border-lime-500/40 bg-lime-500/5 text-lime-300', - accent: 'border-yellow-500/50 bg-yellow-500/10 text-yellow-300', - highlight: 'border-lime-400 bg-lime-500/20 text-lime-200', - muted: 'border-zinc-600 bg-zinc-800/50 text-zinc-400', - header: 'border-lime-500/60 bg-lime-500/15 text-lime-200 font-mono', + default: 'border-border bg-surface', + primary: 'border-primary/50 bg-primary/5', + muted: 'border-border/50 bg-surface-secondary/50', + header: 'border-primary bg-primary/10 font-mono text-sm font-medium text-primary', }; return ( -
+
{children}
); } -// Grid cell for repeated units -function GridCell({ - label, +// Small cell for grid items +function Cell({ + children, variant = 'default', }: { - label: string; + children: React.ReactNode; variant?: 'default' | 'accent' | 'muted'; }) { const variants = { - default: 'border-lime-600/30 bg-lime-600/10 text-lime-400', - accent: 'border-yellow-500/30 bg-yellow-500/10 text-yellow-400', - muted: 'border-zinc-700 bg-zinc-800/30 text-zinc-500', + default: 'border-border bg-background text-foreground-secondary', + accent: 'border-primary/30 bg-primary/5 text-primary', + muted: 'border-border/50 bg-surface-secondary/30 text-foreground-tertiary', }; return ( -
- {label} +
+ {children}
); } -// Main architecture diagram section -function ArchitectureSection({ +// Section wrapper +function Section({ title, subtitle, children, @@ -63,8 +62,8 @@ function ArchitectureSection({ }) { return (
-

{title}

- {subtitle &&

{subtitle}

} +

{title}

+ {subtitle &&

{subtitle}

} {children}
); @@ -72,593 +71,595 @@ function ArchitectureSection({ export default function ArchitecturePage(): React.ReactElement { return ( -
+
-
- {/* Hero */} -
-

- TPMJS Architecture -

-

- A complete overview of the TPMJS platform - from tool discovery to sandboxed execution, - collections, agents, and custom executors. -

-
- - {/* ===================== FULL PLATFORM OVERVIEW ===================== */} - -
- {/* Top Layer - User Products */} - - USER PRODUCTS - - -
- {/* Web App */} -
- - tpmjs.com - -
- - - - - -
-
- - {/* SDK */} -
- - SDK Packages - -
- - - - -
-
- - {/* MCP */} -
- - MCP Protocol - -
- - - - -
-
-
- - {/* Middle Layer - API */} - - API LAYER (Next.js 16) - - -
- - - - - - - - -
- - {/* Bottom Layer - Infrastructure */} - - INFRASTRUCTURE - - -
-
-
DATABASE
-
- - -
-
-
-
EXECUTION
-
- - -
-
-
-
EXTERNAL
-
- - -
-
-
-
- - - {/* ===================== TOOL EXECUTION FLOW ===================== */} - -
- {/* Flow diagram */} -
- {/* Request */} -
- - 1. REQUEST - -
-
- SDK: - registryExecute() -
-
- MCP: - tools/call -
-
- Agent: - tool_call -
-
-
- - {/* Arrow */} -
→
-
↓
- - {/* Resolution */} -
- - 2. RESOLVE - -
-
- Lookup tool by ID -
-
- Resolve executor config -
-
- Build import URL -
-
-
- - {/* Arrow */} -
→
-
↓
- - {/* Executor */} -
- - 3. EXECUTE - -
-
- npm install pkg -
-
- tool.execute(params) -
-
- Return result -
-
-
- - {/* Arrow */} -
→
-
↓
- - {/* Response */} -
- - 4. RESPONSE - -
-
- output: any -
-
- executionTimeMs -
-
- success: boolean -
-
-
-
-
- - - {/* ===================== EXECUTOR ARCHITECTURE ===================== */} - -
- {/* Default Executor */} -
- - DEFAULT EXECUTOR (Vercel Sandbox) - - -
-
SANDBOX VM
-
- - - - -
-
- -
-
- ✓ - Network isolated -
-
- ✓ - Per-request env injection -
-
- ✓ - Automatic npm install -
-
- ✓ - Cold start optimized -
-
-
- - {/* Custom Executor */} -
- - CUSTOM EXECUTOR (User-Deployed) - - -
-
USER INFRASTRUCTURE
-
- - - - -
-
- -
-
- ★ - Custom dependencies pre-installed -
-
- ★ - Your own API keys built-in -
-
- ★ - Custom security policies -
-
- ★ - One-click deploy templates -
-
-
-
- - {/* Executor API Contract */} -
-
EXECUTOR API CONTRACT
-
-
-
POST /execute-tool
-
-
packageName: string
-
name: string
-
params: object
-
env?: object
-
-
-
-
Response
-
-
success: boolean
-
output?: any
-
error?: string
-
executionTimeMs: number
-
-
-
-
- - - {/* ===================== COLLECTIONS & AGENTS ===================== */} - -
- {/* Collections */} -
- - COLLECTION - - -

- Curated bundles of tools exposed via MCP protocol or API. -

- -
-
COLLECTION STRUCTURE
-
-
- name - "Web Scraping Tools" -
-
- tools[] - CollectionTool[] -
-
- executorConfig - ?ExecutorConfig -
-
- visibility - public | private -
-
-
- -
- - - -
-
- - {/* Agents */} -
- - AGENT - - -

- AI-powered assistants with multi-turn conversations and tool access. -

- -
-
AGENT STRUCTURE
-
-
- name - "Research Assistant" -
-
- systemPrompt - string -
-
- collections[] - Collection[] -
-
- model - gpt-4o | claude-3.5-sonnet | ... -
-
-
- -
- - - -
-
-
- - {/* Hierarchy */} -
-
EXECUTOR CONFIG HIERARCHY
-
-
-
System Default
-
Vercel Sandbox
-
-
→
-
-
Collection Config
-
executorConfig
-
-
→
-
-
Agent Override
-
agent.executorConfig
-
-
-

- Agent config overrides Collection config, which overrides System default. +

+ + {/* Hero */} +
+

+ TPMJS Architecture +

+

+ A complete overview of the TPMJS platform - from tool discovery to sandboxed + execution, collections, agents, and custom executors.

- - {/* ===================== DATA FLOW ===================== */} - -
- {/* Sync Pipeline */} -
-
-
npm REGISTRY
-
- - - + {/* ===================== PLATFORM OVERVIEW ===================== */} +
+
+ {/* Top Layer - User Products */} + + USER PRODUCTS + + +
+ {/* Web App */} +
+
+ tpmjs.com +
+
+ Dashboard + Tool Browser + Collection Editor + Agent Builder + Playground +
+
+ + {/* SDK */} +
+
+ SDK Packages +
+
+ @tpmjs/registry-search + @tpmjs/registry-execute + @tpmjs/types + @tpmjs/ui +
+
+ + {/* MCP */} +
+
+ MCP Protocol +
+
+ Claude Desktop + Cursor + Claude Code + Any MCP Client +
-
-
SYNC JOBS
-
- - - -
+ {/* Middle Layer - API */} + + API LAYER (Next.js 16) + + +
+ /api/tools + /api/tools/search + /api/tools/execute + /api/collections + /api/agents + /api/mcp/* + /api/sync/* + /api/health
-
-
PROCESSING
-
- - - -
-
+ {/* Bottom Layer - Infrastructure */} + + INFRASTRUCTURE + -
-
DATABASE
-
- - - -
+
+ +
+ Database +
+
+ PostgreSQL (Neon) + Prisma ORM +
+ + +
+ Execution +
+
+ Vercel Sandbox + Custom Executors +
+ + +
+ External +
+
+ npm Registry + esm.sh CDN +
+
-
- +
- {/* ===================== TOOL SCHEMA ===================== */} - -
-
- {/* Package */} -
- - Package - -
-
- npmPackageName PK + {/* ===================== TOOL EXECUTION FLOW ===================== */} +
+
+
+ {/* Request */} + +
1. REQUEST
+
+
+ SDK: + registryExecute() +
+
+ MCP: + tools/call +
+
+ Agent: + tool_call +
-
npmVersion
-
npmDownloadsLastMonth
-
repositoryUrl
-
author
-
+ + + {/* Resolution */} + +
2. RESOLVE
+
+
+ Lookup tool by ID +
+
+ Resolve executor config +
+
+ Build import URL +
+
+ + + {/* Executor */} + +
3. EXECUTE
+
+
+ npm install pkg +
+
+ tool.execute(params) +
+
+ Return result +
+
+ + + {/* Response */} + +
4. RESPONSE
+
+
+ output: any +
+
+ executionTimeMs +
+
+ success: boolean +
+
+
+
+ - {/* Tool */} -
- - Tool - -
-
- id PK + {/* ===================== EXECUTOR ARCHITECTURE ===================== */} +
+
+ {/* Default Executor */} +
+
+ Default + Vercel Sandbox +
+ + +
+ Sandbox VM
-
name
-
description
-
- inputSchema JSON +
+ Node.js 22 + 2 vCPUs + 2 min timeout + Isolated FS
-
category
-
qualityScore
-
healthStatus
-
- packageId FK + + +
+
+ ✓ + Network isolated +
+
+ ✓ + Per-request env injection +
+
+ ✓ + Automatic npm install +
+
+ ✓ + Cold start optimized
- {/* CollectionTool */} -
- - CollectionTool - -
-
- collectionId FK + {/* Custom Executor */} +
+
+ Custom + User-Deployed +
+ + +
+ User Infrastructure
-
- toolId FK +
+ Vercel + Railway + AWS Lambda + Self-hosted
-
displayName
-
- envOverrides JSON + + +
+
+ ★ + Custom dependencies pre-installed +
+
+ ★ + Your own API keys built-in +
+
+ ★ + Custom security policies +
+
+ ★ + One-click deploy templates
-
position
- {/* Relations */} -
-
- Package 1:N Tool + {/* Executor API Contract */} +
+
+ Executor API Contract
-
- Collection N:M Tool -
-
- Agent N:M Collection -
-
- User 1:N Agent +
+
+
POST /execute-tool
+
+
packageName: string
+
name: string
+
params: object
+
env?: object
+
+
+
+
Response
+
+
success: boolean
+
output?: any
+
error?: string
+
executionTimeMs: number
+
+
-
- +
- {/* Links */} -
-

Learn More

-
- -
Documentation
-
Full SDK and API reference
- - -
Custom Executors
-
Deploy your own execution environment
- - -
Agent Docs
-
Build AI assistants with tools
- -
-
+ {/* ===================== COLLECTIONS & AGENTS ===================== */} +
+
+ {/* Collections */} +
+
+ Collection +
+

+ Curated bundles of tools exposed via MCP protocol or API. +

+ + +
+ Structure +
+
+
+ name + "Web Scraping Tools" +
+
+ tools[] + CollectionTool[] +
+
+ executorConfig + ?ExecutorConfig +
+
+ visibility + public | private +
+
+ + +
+ /api/mcp/{user}/{slug}/http + /api/collections/{id} + Tool-level env overrides +
+
+ + {/* Agents */} +
+
+ Agent +
+

+ AI-powered assistants with multi-turn conversations and tool access. +

+ + +
+ Structure +
+
+
+ name + "Research Assistant" +
+
+ systemPrompt + string +
+
+ collections[] + Collection[] +
+
+ model + gpt-4o | claude-3.5... +
+
+ + +
+ /agents/{id}/chat + Streaming: SSE tool_call events + Persistent conversations +
+
+
+ + {/* Hierarchy */} +
+
+ Executor Config Hierarchy +
+
+ +
System Default
+
Vercel Sandbox
+ + → + ↓ + +
Collection Config
+
executorConfig
+ + → + ↓ + +
Agent Override
+
agent.executorConfig
+ +
+

+ Agent config overrides Collection config, which overrides System default. +

+
+
+ + {/* ===================== DATA FLOW ===================== */} +
+
+
+ +
+ npm Registry +
+
+ keyword: "tpmjs" + tpmjs field + package.json +
+ + + +
Sync Jobs
+
+ Changes Feed (2min) + Keyword Search (15min) + Metrics Sync (1hr) +
+ + + +
Processing
+
+ Validate tpmjs field + Extract inputSchema + Calculate quality score +
+ + + +
+ Database +
+
+ Tool (metadata) + Package (npm info) + inputSchema (JSON) +
+ +
+
+
+ + {/* ===================== TOOL SCHEMA ===================== */} +
+
+
+ {/* Package */} + +
Package
+
+
+ npmPackageName PK +
+
npmVersion
+
npmDownloadsLastMonth
+
repositoryUrl
+
author
+
+ + + {/* Tool */} + +
Tool
+
+
+ id PK +
+
name
+
description
+
+ inputSchema JSON +
+
category
+
qualityScore
+
healthStatus
+
+ packageId FK +
+
+ + + {/* CollectionTool */} + +
CollectionTool
+
+
+ collectionId FK +
+
+ toolId FK +
+
displayName
+
+ envOverrides JSON +
+
position
+
+ +
+ + {/* Relations */} +
+
+ Package 1:N Tool +
+
+ Collection N:M Tool +
+
+ Agent N:M Collection +
+
+ User 1:N Agent +
+
+
+
+ + {/* Links */} +
+

Learn More

+
+ +
Documentation
+
Full SDK and API reference
+ + +
Custom Executors
+
+ Deploy your own execution environment +
+ + +
Agent Docs
+
+ Build AI assistants with tools +
+ +
+
+
);