diff --git a/apps/web/src/app/docs/architecture/page.tsx b/apps/web/src/app/docs/architecture/page.tsx new file mode 100644 index 0000000..aba94bf --- /dev/null +++ b/apps/web/src/app/docs/architecture/page.tsx @@ -0,0 +1,665 @@ +'use client'; + +import Link from 'next/link'; +import { AppHeader } from '~/components/AppHeader'; + +// Chip-style box component +function ChipBox({ + children, + className = '', + variant = 'default', +}: { + children: React.ReactNode; + className?: string; + variant?: 'default' | 'accent' | 'highlight' | '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', + }; + + return ( +
+ {children} +
+ ); +} + +// Grid cell for repeated units +function GridCell({ + label, + variant = 'default', +}: { + label: string; + 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', + }; + + return ( +
+ {label} +
+ ); +} + +// Main architecture diagram section +function ArchitectureSection({ + title, + subtitle, + children, +}: { + title: string; + subtitle?: string; + children: React.ReactNode; +}) { + return ( +
+

{title}

+ {subtitle &&

{subtitle}

} + {children} +
+ ); +} + +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. +

+
+ + + {/* ===================== DATA FLOW ===================== */} + +
+ {/* Sync Pipeline */} +
+
+
npm REGISTRY
+
+ + + +
+
+ +
+
SYNC JOBS
+
+ + + +
+
+ +
+
PROCESSING
+
+ + + +
+
+ +
+
DATABASE
+
+ + + +
+
+
+
+ + + {/* ===================== 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
+ +
+
+
+
+ ); +}