# adamjmurray/producer-pal architecture

> Architecture diagram of the GitHub repository adamjmurray/producer-pal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adamjmurray/producer-pal
- Repository: https://github.com/adamjmurray/producer-pal

## Overview

Producer Pal is an Ableton Live control server exposed through MCP and an open REST API, with AI optional. A user or AI client sends a request to the server, which exposes tools for working with a Live Set; Live operations cross the Max/V8-to-Node boundary through an RPC adapter. The repository also contains notation support, Live-library discovery, persistent assistant context, and browser interfaces. The README documents the main product surface; sampled source confirms REST request handling, selected RPC-backed services, and web app startup, but not every tool-to-adapter call path.

Main entry points: [`src/mcp-server/rpc/node-request-protocol.ts`](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/rpc/node-request-protocol.ts) (Node RPC routes), [`src/mcp-server/mcp-server.ts`](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/mcp-server.ts) (MCP server), [`src/tools`](https://github.com/adamjmurray/producer-pal/tree/main/src/tools) (Live tools), [`src/mcp-server/routes/rest-api-routes.ts`](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/routes/rest-api-routes.ts) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server interfaces"]
  node_mcp["MCP server<br/>[mcp-server.ts]"]
  node_rest["REST API<br/>[rest-api-routes.ts]"]
  node_express["HTTP app"]
  node_portal["Portal integration"]
end

subgraph group_live["Live control"]
  node_tools["Live tools"]
  node_adapter["Live API adapter"]
  node_rpc["Node RPC routes"]
  node_notation["Music notation<br/>[notation.ts]"]
end

subgraph group_assistant["Assistant context"]
  node_skills["Built-in skills<br/>[build-skills.ts]"]
  node_context["Context and memory"]
  node_memory[("Memory store<br/>[memory-store.ts]")]
  node_customskills[("Custom skills")]
  node_projectcontext["Project context backup"]
end

subgraph group_web["Browser experience"]
  node_webui["Web UI<br/>[App.tsx]"]
  node_webentry["Web app entry<br/>[main.tsx]"]
  node_preset[("Chat presets<br/>[preset-storage.ts]")]
end

subgraph group_discovery["Music discovery"]
  node_libraryroutes["Library RPC routes<br/>[library-routes.ts]"]
  node_libraryquery["Library search<br/>[candidate-query.ts]"]
  node_livedb[("Live browser DB<br/>[live-db.ts]")]
end

node_user(("Musician / client"))
node_liveapp(("Ableton Live"))

node_user -->|"sends MCP requests"| node_mcp
node_user -->|"sends HTTP requests"| node_rest
node_rest -->|"registers routes"| node_express
node_mcp -->|"exposes tools"| node_tools
node_rest -->|"validates and invokes"| node_tools
node_tools -->|"parses notation"| node_notation
node_tools -->|"requests Live operations"| node_adapter
node_adapter -->|"controls Live"| node_liveapp
node_adapter -->|"dispatches Node requests"| node_rpc
node_rpc -->|"dispatches library calls"| node_libraryroutes
node_libraryroutes -->|"runs searches"| node_libraryquery
node_libraryquery -->|"queries"| node_livedb
node_rpc -->|"dispatches context calls"| node_context
node_context -->|"reads and writes"| node_memory
node_rpc -->|"dispatches skill calls"| node_customskills
node_rpc -->|"dispatches sync"| node_projectcontext
node_webentry -->|"renders"| node_webui
node_webui -->|"loads and saves"| node_preset
node_user -->|"uses browser UI"| node_webui
node_mcp -->|"provides assistant guidance"| node_skills
node_mcp -.->|"supports portal mode"| node_portal

click node_mcp "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/mcp-server.ts"
click node_rest "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/routes/rest-api-routes.ts"
click node_express "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/create-express-app.ts"
click node_tools "https://github.com/adamjmurray/producer-pal/tree/main/src/tools"
click node_adapter "https://github.com/adamjmurray/producer-pal/blob/main/src/live-api-adapter/live-api-adapter.ts"
click node_rpc "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/rpc/node-request-protocol.ts"
click node_notation "https://github.com/adamjmurray/producer-pal/blob/main/src/notation/notation.ts"
click node_skills "https://github.com/adamjmurray/producer-pal/blob/main/src/skills/build-skills.ts"
click node_context "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/global-context/global-context-node-routes.ts"
click node_memory "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/memory/memory-store.ts"
click node_customskills "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/skills-custom/custom-skills-store.ts"
click node_projectcontext "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/project-context-backup/project-context-backup-node-routes.ts"
click node_webui "https://github.com/adamjmurray/producer-pal/blob/main/webui/src/components/App.tsx"
click node_webentry "https://github.com/adamjmurray/producer-pal/blob/main/webui/src/main.tsx"
click node_preset "https://github.com/adamjmurray/producer-pal/blob/main/webui/src/hooks/settings/presets/preset-storage.ts"
click node_libraryroutes "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/live-library/library-routes.ts"
click node_libraryquery "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/live-library/query/candidate-query.ts"
click node_livedb "https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/live-library/live-db.ts"
click node_portal "https://github.com/adamjmurray/producer-pal/blob/main/src/portal/producer-pal-portal.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_rest,node_express,node_portal,node_user toneBlue
class node_tools,node_adapter,node_rpc,node_notation toneAmber
class node_skills,node_context,node_memory,node_customskills,node_projectcontext toneMint
class node_webui,node_webentry,node_preset toneRose
class node_libraryroutes,node_libraryquery,node_livedb,node_liveapp toneIndigo
```

## Components

### Server interfaces

- [MCP server](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/mcp-server.ts): `src/mcp-server/mcp-server.ts`
- [REST API](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/routes/rest-api-routes.ts): `src/mcp-server/routes/rest-api-routes.ts`
- [HTTP app](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/create-express-app.ts): `src/mcp-server/create-express-app.ts`
- [Portal integration](https://github.com/adamjmurray/producer-pal/blob/main/src/portal/producer-pal-portal.ts): `src/portal/producer-pal-portal.ts`

### Live control

- [Live tools](https://github.com/adamjmurray/producer-pal/tree/main/src/tools): `src/tools`
- [Live API adapter](https://github.com/adamjmurray/producer-pal/blob/main/src/live-api-adapter/live-api-adapter.ts): `src/live-api-adapter/live-api-adapter.ts`
- [Node RPC routes](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/rpc/node-request-protocol.ts): `src/mcp-server/rpc/node-request-protocol.ts`
- [Music notation](https://github.com/adamjmurray/producer-pal/blob/main/src/notation/notation.ts): `src/notation/notation.ts`

### Assistant context

- [Built-in skills](https://github.com/adamjmurray/producer-pal/blob/main/src/skills/build-skills.ts): `src/skills/build-skills.ts`
- [Context and memory](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/global-context/global-context-node-routes.ts): `src/mcp-server/helpers/global-context/global-context-node-routes.ts`
- [Memory store](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/memory/memory-store.ts): `src/mcp-server/helpers/memory/memory-store.ts`
- [Custom skills](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/skills-custom/custom-skills-store.ts): `src/mcp-server/helpers/skills-custom/custom-skills-store.ts`
- [Project context backup](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/helpers/project-context-backup/project-context-backup-node-routes.ts): `src/mcp-server/helpers/project-context-backup/project-context-backup-node-routes.ts`

### Browser experience

- [Web UI](https://github.com/adamjmurray/producer-pal/blob/main/webui/src/components/App.tsx): `webui/src/components/App.tsx`
- [Web app entry](https://github.com/adamjmurray/producer-pal/blob/main/webui/src/main.tsx): `webui/src/main.tsx`
- [Chat presets](https://github.com/adamjmurray/producer-pal/blob/main/webui/src/hooks/settings/presets/preset-storage.ts): `webui/src/hooks/settings/presets/preset-storage.ts`

### Music discovery

- [Library RPC routes](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/live-library/library-routes.ts): `src/mcp-server/live-library/library-routes.ts`
- [Library search](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/live-library/query/candidate-query.ts): `src/mcp-server/live-library/query/candidate-query.ts`
- [Live browser DB](https://github.com/adamjmurray/producer-pal/blob/main/src/mcp-server/live-library/live-db.ts): `src/mcp-server/live-library/live-db.ts`

### Other components

- **Musician / client**
- **Ableton Live**

## Connections

- Musician / client → MCP server: sends MCP requests
- Musician / client → REST API: sends HTTP requests
- REST API → HTTP app: registers routes
- MCP server → Live tools: exposes tools
- REST API → Live tools: validates and invokes
- Live tools → Music notation: parses notation
- Live tools → Live API adapter: requests Live operations
- Live API adapter → Ableton Live: controls Live
- Live API adapter → Node RPC routes: dispatches Node requests
- Node RPC routes → Library RPC routes: dispatches library calls
- Library RPC routes → Library search: runs searches
- Library search → Live browser DB: queries
- Node RPC routes → Context and memory: dispatches context calls
- Context and memory → Memory store: reads and writes
- Node RPC routes → Custom skills: dispatches skill calls
- Node RPC routes → Project context backup: dispatches sync
- Web app entry → Web UI: renders
- Web UI → Chat presets: loads and saves
- Musician / client → Web UI: uses browser UI
- MCP server → Built-in skills: provides assistant guidance
- MCP server → Portal integration: supports portal mode