tpmjs/docs/diagrams/README.md

TPMJS Architecture Diagrams

Visual documentation of the TPMJS system architecture, optimized for quick understanding.

Diagram Index

Diagram	Purpose	View
System Overview	10-second understanding of TPMJS	SVG
Tool Discovery	How npm packages become tools	SVG
Tool Execution	How tools get called and run	SVG
Data Model	Database domain groups	SVG

---

1. System Overview

Purpose: Understand what TPMJS is at a glance.

Flow: Inputs → TPMJS Core → Execution → Outputs

• Inputs: npm Registry, AI Clients, Web Users, Bridge CLI (WIP)
• Core: API Gateway, Tool Registry, Schema Pipeline
• Execution: AI Agents, Executor (Railway)
• Outputs: Tool Results, MCP Responses, SSE Streams

---

2. Tool Discovery Flow

Purpose: Show how npm packages become TPMJS tools (Hero Path).

Flow: npm Registry → Sync Workers → Schema Extraction → Tool Registry → Available

1. npm Registry - Packages with tpmjs keyword
2. Sync Workers - Changes feed (2 min), Keyword search (15 min), Metrics (hourly)
3. Schema Extraction - Import via esm.sh, Extract schema, AI assist, Convert to Zod
4. Tool Registry - Database storage (Package + Tool tables)
5. Available - Web UI, MCP Protocol, REST API

---

3. Tool Execution Flow

Purpose: Show how tools get called and executed via two paths.

Path A (Web Playground):

User Prompt → AI Agent → Tool Schema → Executor → SSE Response

Path B (MCP Protocol):

AI Client → JSON-RPC → MCP Handler → Executor → JSON-RPC Response

Both paths converge at the Executor which handles:

• Resolution (Agent → Collection → Default)
• Railway execution (POST /execute-tool)
• Dynamic import via esm.sh

---

4. Data Model

Purpose: Database structure reference (domain groups, not individual tables).

6 Domain Groups:

Group	Contains
Packages & Tools	Package, Tool, ToolVersion
Users & Auth	User, Session, Account, APIKey
Agents & Chats	Agent, Chat, Message, Prompt
Collections	Collection, CollectionTool
Execution & Usage	Execution, Usage, Feedback
Sync & Scenarios	SyncCheckpoint, SyncLog, Scenario

---

Visual Legend

Arrow Styles

Style	Meaning
Solid →	Synchronous request/response
Dashed ⇢	Async, event, or cron job
Dotted ··→	WIP / Future feature

Color Coding

Color	Domain
Blue	API / Gateway
Green	Database / Storage
Orange	External Services
Purple	AI / LLM
Pink	Execution
Gray	WIP Features

---

Editing Diagrams

Diagrams are written in D2 and rendered to SVG.

Prerequisites

# Install D2
brew install d2

Render a diagram

cd docs/diagrams
d2 01-overview.d2 01-overview.svg --layout=elk

Render all diagrams

for f in *.d2; do d2 "$f" "${f%.d2}.svg" --layout=elk; done

Source Files

• 01-overview.d2 - System Overview
• 02-discovery.d2 - Tool Discovery Flow
• 03-execution.d2 - Tool Execution Flow
• 04-data-model.d2 - Data Model

---

Version History

• v2 (Current) - Split into 4 focused diagrams, left-to-right flow
• v1 - Single comprehensive diagram (archived as ../architecture-v1.d2)