# Architecture: six-pillar fail-closed pipeline

> ToolMesh runs every tool call through six pillars: Any Backend, Code Mode, Audit, Authz, Credentials, Output Gate — with pipeline diagram and extension model.

Canonical: https://www.toolmesh.io/en/architecture/

ToolMesh is a Go middleware that orchestrates, authorizes, and secures the execution of tool calls between AI agents and backend infrastructure.

## Execution Pipeline

Every tool call passes through a fail-closed pipeline. If any step rejects (AuthZ, Gate), the entire execution stops. No partial results leak through.

## The Six Pillars

| Pillar | Implementation | Backed by |
|--------|---------------|-----------|
| **Any Backend** | MCP servers (HTTP/STDIO) + REST APIs via DADL | Go MCP SDK + DADL parser |
| **Code Mode** | `list_tools` + `execute_code` — LLMs write JS instead of JSON | AST-parsed tool calls |
| **Audit** | Every tool call logged structurally | slog (write-only) or SQLite (queryable) |
| **Authorization** | User → Plan → Tool relationships | OpenFGA |
| **Credential Store** | Secrets injected at runtime, never in prompts | Env vars (`CREDENTIAL_*`), extensible |
| **Output Gate** | JS policies validate input/output | goja (Go JS engine) |

## Extension Model

Three components are extensible via a registry pattern (inspired by Go's `database/sql` drivers):

| Component | Registry Function | Built-in | Config |
|-----------|-------------------|----------|--------|
| **Credential Store** | `credentials.Register()` | `embedded` (env vars) | `CREDENTIAL_STORE=<name>` |
| **Tool Backend** | `backend.Register()` | `mcp`, `rest` (DADL), `echo` | `config/backends.yaml` |
| **Gate Evaluator** | `gate.RegisterEvaluator()` | `goja` (JavaScript) | `GATE_EVALUATORS=<list>` |

Extensions register via `init()` functions. Enterprise extensions live in a separate module and are included via Go build tags:

```bash
go build -tags enterprise ./cmd/toolmesh
```

### Enterprise Extensions (Planned)

| Component | Extension | Description |
|-----------|-----------|-------------|
| Credential Store | `InfisicalStore` | Infisical Secrets Manager integration |
| Credential Store | `VaultStore` | HashiCorp Vault / OpenBao integration |
| Gate Evaluator | `Compliance-LLM` | LLM-based content classification |

## Project Structure

```
toolmesh/
├── cmd/
│   └── toolmesh/          # Main entrypoint (MCP server)
├── config/
│   └── openfga/           # Authorization model (model.fga), tuples (tuples.json), setup script
├── internal/
│   ├── mcp/               # MCP server (Streamable HTTP + STDIO)
│   ├── backend/           # ToolBackend interface + MCPAdapter + RESTAdapter
│   ├── executor/          # ExecuteTool pipeline (AuthZ → Creds → Gate → Exec → Audit)
│   ├── audit/             # Audit store interface + log/sqlite implementations
│   ├── authz/             # OpenFGA authorization
│   ├── credentials/       # Credential store interface + EmbeddedStore
│   ├── gate/              # Output gate (goja policy engine)
│   ├── userctx/           # UserContext propagation
│   └── config/            # Environment-based configuration
├── config/                # Backend config (backends.yaml, users.yaml, apikeys.yaml)
├── tools/                 # TypeScript tool definitions (canonical source)
├── policies/              # JavaScript gate policies
└── docs/                  # Documentation
```