System Architecture & Deployment

PMS Sync connects on-premises Aderant Expert with cloud-hosted Clio Operate (built on the Sharedo platform). The architecture enforces least-privilege exposure: the on-premises SQL agent is read-only, all cloud communication runs over an outbound-only Azure Relay tunnel on port 443, and no inbound firewall ports are opened.

1. Component Architecture

The integration divides responsibilities across four modular components spanning client on-premises infrastructure, an Azure Relay rendezvous, Alterspective hosted services, and the Clio Operate SaaS tenant.

2. Network & Tunnel Topology

Cloud components never initiate direct inbound TCP connections to the client network. The on-premises agent establishes an outbound TLS WebSocket (WSS/HTTPS) to an Azure Relay Hybrid Connection on port 443. The proxy connects to the same relay using separate shared-access credentials.

[ Staff Browser / Embedded Widget ]
               │
               ▼ HTTPS (Port 443 -> Container 3060)
┌─────────────────────────────────────────────────────────┐
│ AderantImportPortal (Next.js 15)                        │
└──────────────────────────┬──────────────────────────────┘
                           │ Internal HTTPS (Port 3050)
┌──────────────────────────▼──────────────────────────────┐
│ ShareDoAderantAPIProxy (Port 3050)                      │
│ - Mints embed JWT, validates per-org mappings           │
│ - Signs relay dispatches with Send SAS key              │
└──────────────────────────┬──────────────────────────────┘
                           │ Outbound HTTPS/WSS (Port 443)
                           ▼
┌─────────────────────────────────────────────────────────┐
│ Azure Relay Rendezvous (*.servicebus.windows.net)       │
│ - Hybrid Connection: aderant-agent                      │
│ - Dual HMAC-SHA256 SAS rules: proxy-send / agent-listen │
└──────────────────────────▲──────────────────────────────┘
                           │ Outbound TLS (Port 443)
┌──────────────────────────┴──────────────────────────────┐
│ Aderant SQL API Agent (Port 4102 on-prem Windows host)  │
│ - Supervised Windows Service (MSI/WinSW) or Docker      │
│ - Listens on Azure Relay; answers local /health probes  │
└──────────────────────────┬──────────────────────────────┘
                           │ Internal LAN (Port 1433 TDS)
┌──────────────────────────▼──────────────────────────────┐
│ Aderant Expert SQL Server (Client Infrastructure)        │
│ - Read-only login: db_datareader                         │
└─────────────────────────────────────────────────────────┘

Network Egress & Allow-Lists

3. Data Flow & Role Cardinality Enforcement

Matter import follows a multi-phase pipeline designed to guarantee idempotency and enforce strict participant role constraints before any write operation reaches Clio Operate:

1. Search: Staff query matters by code or title in the Portal (port 3060). The request routes to the Proxy (port 3050), across Azure Relay to the SQL Agent (port 4102). The agent runs parameterized queries against Aderant views and returns candidate matches with existing import badges.
2. Preview & Cardinality Validation: When a matter is opened for preview, the Proxy retrieves the complete matter payload including all associated parties. The Proxy introspects the target Clio Operate work-type configuration to evaluate:
   • Single-Allocation Roles: Strict 1:1 roles (such as Claim Handler, Responsible Partner, or Primary Client Contact) are validated. If multiple parties compete for a single slot, the UI flags the conflict and requires explicit user resolution.
   • Multi-Allocation Roles: Roles permitting multiple assignees (such as Counsel, Expert, or Additional Insured) allow batch association.
   • User-Eligible Roles: Validates whether the importing staff member can be bound to designated internal roles, preventing unauthorized permission escalation.
3. Execution & Capacity Guard: Upon user confirmation, the Proxy applies write-side capacity guards to prevent race conditions:
   • Resolves or creates ODS Parties in Clio Operate.
   • Creates the Work Item (Matter), stamping the external Aderant matter code and UNO for idempotency.
   • Binds participants with validated role assignments and default matter security teams.

4. Model Context Protocol (MCP) Integration

Both the API Proxy (port 3050) and the on-premises SQL API Agent (port 4102) expose Model Context Protocol (MCP) interfaces over Streamable HTTP at /mcp. This surface enables AI assistants (including Claude and internal automation agents) to safely inspect schema definitions, execute diagnostic probes, and query matter records under strict OAuth 2.1 token authorization issued by Alterspective Keystone.

• pms-sql-api:read — Permits schema discovery, matter search, and diagnostic introspection.
• pms-sql-api:write — Reserved for authorized synchronization actions; blocked by default on read-only agents.

5. Security Guarantees