Architecture & Dependencies

A deeper technical companion to the Architecture flow page. It answers three questions precisely: what the moving parts are and what they depend on, whether any AI runs when a user imports a matter, and whether the system exposes a Model Context Protocol (MCP) service that an AI agent can use. Short version: a live user import is pure deterministic code — no AI, no MCP in the loop — while AI and MCP exist as separate, well-bounded capabilities described below.

1. The four building blocks

Think of it as a relay team — each part has exactly one job.

2. How one import flows

The money path: a user picks a matter and it becomes a Clio Operate work item. Reads go to Aderant (left); writes go to Clio Operate (right). The Proxy is the only writer.

User + Widget
   │  1 search / select a matter
   ▼
Portal ───2 preview / import (with org config)──▶ Proxy
                                                   │  3 read matter + parties
                                                   ▼
                                                 SQL API ──▶ Aderant SQL (on-prem)
                                                   │  4 transform (deterministic, sandboxed)
                                                   ▼
                                                 Clio Operate API
                                                   │  5 create ODS parties + work item + key dates
                                                   ▼
                                           Portal / Proxy audit
                                      (6 history row or audit event)

3. What runs during a user import — and what doesn't

This is the question most people actually want answered. When a user clicks Preview or Import, the runtime path is 100% deterministic. No language model is called, and the MCP service is not involved. The per-tenant field transform runs inside a QuickJS WebAssembly sandbox — sandboxed JavaScript with no network, no I/O, and no timers. Provided a transform does not call non-deterministic globals such as Date.now() or Math.random(), the same input produces the same output.

4. Where the AI actually lives (design-time only)

AI assistance exists, but it is used before any import — when a consultant or administrator authors a work-type mapping transform. The portal offers two admin-only helpers that call the Alterspective Synapse LLM service:

• Suggest — generate a draft JavaScript transform for a field mapping.
• Repair — fix a transform that is failing validation.

The administrator reviews the suggestion and saves it as mapping configuration. From then on, every import just executes that saved deterministic snippet. If Synapse were offline, imports would be completely unaffected — only the authoring assistant would be unavailable.

5. The MCP service (for AI agents)

Yes — the system exposes two Model Context Protocol services that an AI agent can use. They are a completely separate surface from the user import path: a different route (/mcp), different authentication (Keystone OAuth 2.1 bearer tokens), and different callers (agents, not the browser). The Portal deliberately has no MCP service — it is the human UI, and its capabilities are already exposed by the two backends.

Proxy MCP — 7 tools (read + gated write)

SQL API MCP — 5 tools (read-only)

The elegant part: an agent calling import_matter ends up running the exact same deterministic import code a human triggers — the MCP tool simply calls the proxy's own HTTP API in-process. So AI can initiate an import, but no AI runs inside it. There is no arbitrary-SQL tool by design; every database read is whitelisted and parameterised.

6. Dependency map (key libraries)

The Sharedo widget (pms-sync-embed) is built on the Alterspective Foundry SDK and pulls its packages from GitHub Packages.

7. External systems we depend on