142 lines
3.7 KiB
Markdown
142 lines
3.7 KiB
Markdown
# TPMJS Architecture Diagrams
|
|
|
|
Visual documentation of the TPMJS system architecture, optimized for quick understanding.
|
|
|
|
## Diagram Index
|
|
|
|
| Diagram | Purpose | View |
|
|
|---------|---------|------|
|
|
| [System Overview](./01-overview.svg) | 10-second understanding of TPMJS | [SVG](./01-overview.svg) |
|
|
| [Tool Discovery](./02-discovery.svg) | How npm packages become tools | [SVG](./02-discovery.svg) |
|
|
| [Tool Execution](./03-execution.svg) | How tools get called and run | [SVG](./03-execution.svg) |
|
|
| [Data Model](./04-data-model.svg) | Database domain groups | [SVG](./04-data-model.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](https://d2lang.com/) and rendered to SVG.
|
|
|
|
### Prerequisites
|
|
```bash
|
|
# Install D2
|
|
brew install d2
|
|
```
|
|
|
|
### Render a diagram
|
|
```bash
|
|
cd docs/diagrams
|
|
d2 01-overview.d2 01-overview.svg --layout=elk
|
|
```
|
|
|
|
### Render all diagrams
|
|
```bash
|
|
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`)
|