Skip to main content

PMS Sync — Deployment Topology

Network boundaries and component allocation across three ownership zones: the enterprise on-premises network, Alterspective-hosted services, and the customer Sharedo tenant.

Deployment architecture across three distinct ownership zones: the enterprise on-premises environment, Alterspective-hosted multi-tenant services, and the customer Sharedo tenant.

ZONE 1: ON-PREMISES Enterprise Network · Outbound Only Aderant Expert SQL Server Port 1433 (TDS) · NTLM authentication Source of truth for matters, clients, and parties. AderantSQLAPITypeScript Express 5 · Port 4102 · Read Engine Parameterised queries against column whitelist. Streamable /mcp · Scope: pms-sql-api:read Azure Relay Listener Outbound TLS 443 · SAS Token Auth Zero inbound firewall ports required. hyco-https bridge to cloud API Proxy. Local dev fallback: ngrok tunnel ZONE 2: ALTERSPECTIVE CLOUD Hosted Core · Coolify Managed ShareDoAderantAPIProxy Express 4 · Port 3050 · Clean Architecture src/{domain, application, infrastructure, presentation} runAderantWriteGate · Single Write Choke-Point Streamable /mcp (7 tools) · OAuth 2.1 scopes Capacity guard: WorkTypeParticipantRole AderantImportPortal Next.js 15 · Port 3060 · React 19 UI shell · Signs x-org-assertion (HMAC-SHA256) pms-sync.alterspective.com.au Supabase & Keystone Identity aderant_org_configs (tenant secrets) aderant_write_audit (fail-closed HTTP 503) Keystone: OIDC login & OAuth 2.1 JWKS verification Synapse LLM: GPU mapping assistance ZONE 3: SHAREDO TENANT Enterprise Cloud Workspace pms-sync-embed Widget Foundry SDK ^0.6 · Sharedo IDE Iframes Portal with SSO JWT via #fragment. Deployed via Foundry CLI. Sharedo Linked Services Outbound connectors with shared secrets aderant-import-proxy · aderant-sql-api Sharedo / Clio Operate APIs REST Target: Work Items & ODS Parties Participant role cardinality enforced: WorkTypeParticipantRole.canBeAssignedMultiple Single-capacity roles guarded against duplicates. Dynamic user-eligible role resolution.
Deployment topology across three ownership zones. Communication with on-premises SQL uses outbound-only TLS 443 via Azure Relay Hybrid Connection. The cloud Proxy is the single governed write gateway into Sharedo.
Zone 1: Enterprise On-Premises Environment Zone 2: Alterspective Hosted Cloud Services Zone 3: Customer Sharedo Tenant Azure Relay Transport & Write Security

Zone 1 On-premise install

Deployed in enterprise network · Outbound-only

Aderant Expert SQL Server

Port 1433 (TDS)NTLM Auth

The on-premises practice management system. Houses client and matter records, financial data, and party relationships. Strictly accessed via read-only parameterised queries.

Aderant SQL API Agent read

AderantSQLAPITypeScriptPort 4102Express 5

Queries the Aderant SQL Server (clients, matters, employees, and dynamic table views). Runs as a Windows Service (WinSW) or Docker container. Exposes streamable /mcp with RFC 9728 discovery.

Outbound Transport Bridge

Azure Relay Hybrid ConnectionPort 443 TLS

Outbound-only connection using Shared Access Signature (SAS) token authorization. The hosted Proxy connects securely to the on-premises agent without opening inbound firewall ports. Local development environments can use ngrok as a fallback.

Aderant REST / CRUD Proxy write

Phase 2 Write-BackNTLM Proxy

Wraps Aderant Expert REST APIs for bidirectional matter updates under runAderantWriteGate governance.

Read boundary: The SQL API is read-only and cannot alter on-premises database state.

Zone 2 Hosted services

Multi-tenant cloud platform · Coolify managed

API Proxy & Orchestrator readwrite

ShareDoAderantAPIProxyPort 3050Clean Architecture

Organized into domain, application, infrastructure, and presentation layers. Single write gateway into Sharedo, orchestrates Azure Relay communication, executes transforms, and serves streamable /mcp (7 tools) under Keystone OAuth 2.1.

Import Portal

AderantImportPortalPort 3060Next.js 15

Web UI for matter search, preview generation, role cardinality conflict management, and import execution. Mints HMAC-signed x-org-assertion headers to verify tenant identity on every proxy call.

Keystone Identity Provider

identity.alterspective.com.auOIDC + OAuth 2.1

Central identity authority. Validates portal user logins and issues RFC 9728-discoverable OAuth 2.1 tokens with remote JWKS verification.

Supabase Config & Audit Store

aderant_org_configsaderant_write_audit

Stores tenant credentials and configuration. Houses the pre-execution audit table (aderant_write_audit); if database commits fail, the write gate fails closed with HTTP 503.

Synapse AI Gateway

synapse-api.alterspective.com.auGPU Inference

Private GPU inference service for authoring mapping transforms and analyzing work type schemas.

Zone 3 Into the client tenant

Deployed into customer Sharedo / Clio Operate

PMS Sync Embed Widget

Foundry SDK ^0.6/_ideFiles/Alterspective/PmsSync/Embed

Embeds the Import Portal directly inside the Sharedo IDE via iframe. Initiates single sign-on using a signed JWT handoff delivered in URL #fragment, isolating user sessions to roles: ['embedded'].

Linked Services

aderant-import-proxyaderant-sql-api

Sharedo outbound connectors that securely route requests to the hosted Proxy using server-side shared secrets.

Sharedo Work Items & Parties target

ODS PartiesWork ItemsKey Dates

Aderant matters land as native Sharedo work items. Participant roles are introspected (WorkTypeParticipantRole.canBeAssignedMultiple) to enforce single-capacity allocation and prevent duplicate role errors.

Framing boundary: CSP frame-ancestors allows only authorized customer Sharedo domains.
Transport: Hosted Proxy ⇄ On-Prem SQL API via Azure Relay Hybrid Connection (TLS 443, SAS tokens) Embed SSO: Sharedo Widget ⇄ Portal iframe (Signed JWT via #fragment) Assertion: Portal ⇄ Proxy (HMAC-SHA256 x-org-assertion) Correlation: x-correlation-id propagated end-to-end

Matter import execution lifecycle

01 SSO & Frame Launch Widget mints short-lived JWT Passed via iframe #fragment roles: ['embedded'] 02 Matter Search User queries matter / client Portal → Proxy (:3050) HMAC x-org-assertion 03 On-Premises Read Proxy queries SQL API (:4102) Azure Relay Hybrid Conn TLS 443 · SAS Token Auth 04 Preview & Cardinality Evaluates canBeAssignedMultiple Surfaces [Single]/[Multi] flags Mints previewHash nonce 05 User Confirmation User reviews mappings/warnings Clicks Import CTA confirm: true + previewHash 06 runAderantWriteGate Validates flag & previewHash Writes pre-audit to Supabase Fail-closed: HTTP 503 07 Sharedo Upstream Creation Creates ODS parties & work item Capacity guard prevents 400/500 Audit outcome: 200 OK
End-to-end matter import transaction path showing SSO token isolation, Azure Relay transport, preview validation, the unified write gate, and fail-closed audit commitment.
  1. SSO Authentication: The user accesses the PMS Import page in Sharedo. The embed widget fetches a signed handoff JWT from the API Proxy (/api/embed/handoff) and frames the Portal via URL #fragment, ensuring the token is omitted from referrer headers and server logs. The Portal assigns roles: ['embedded'] without administrative rights.
  2. Matter Search: The user queries an Aderant matter by code or client. The Portal sends GET /api/import/matters/search to the Proxy, signing the request with an HMAC-SHA256 x-org-assertion header.
  3. On-Premises Read: The Proxy calls the on-premises SQL API agent over an Azure Relay Hybrid Connection (outbound-only TLS 443 with SAS token authorization; zero inbound firewall ports). The agent executes parameterised, column-whitelisted SQL against Aderant Expert.
  4. Preview & Role Cardinality Introspection: The Proxy runs POST /api/import/matter/{uno}/preview. It maps matter fields and introspects Sharedo work type schemas via WorkTypeParticipantRole.canBeAssignedMultiple. Single-capacity roles (e.g. Primary Owner, Client) are evaluated; potential duplicate conflicts trigger warning badges. The Proxy issues a single-use previewHash nonce.
  1. User Confirmation: The user reviews the mapped fields, dates, and participant roles. Clicking Import dispatches POST /api/import/matter/{uno} with confirm: true and the exact previewHash nonce.
  2. Unified Write Gate (runAderantWriteGate): The Proxy validates that the tenant's aderant_write_enabled flag is active in Supabase, checks the single-use nonce, and inserts a pre-execution row into aderant_write_audit. If the audit database is unreachable, the request fails closed with HTTP 503 and halts.
  3. Sharedo Creation & Capacity Guard: The Proxy invokes Sharedo APIs to create ODS parties, instantiate the work item, and set key dates. Write-side capacity tracking enforces single-allocation rules, substituting or skipping excess duplicates to prevent upstream errors.
  4. Audit Completion & Reconcile: The final execution status is committed to aderant_write_audit, returning the new Sharedo work item ID. Periodic reconciliation jobs detect matter closure drift between Aderant and Sharedo.
Deployment isolation model: The on-premises SQL API agent and optional REST proxy run within the enterprise network, communicating outbound over Azure Relay Hybrid Connection. The hosted Portal (:3060) and API Proxy (:3050) are multi-tenant services. Each enterprise tenant is strictly isolated by verified Keystone token claims, server-side Supabase configuration, and cryptographic assertions.

Visual deployment topology documentation for PMS Sync. Innovation Hub reference: Practice Management → PMS Sync. Regenerate by re-reading the sources below, not by editing figures here.

Knowledge base: Reference/Registries/estate-projects/EP-alterspective-aderant.md and Reference/Alterspective/assets/AA-006-Aderant-OOTB-vs-Alterspective-One-Pager.md in Alterspective-Intelligence.

Architecture references: AGENTS.md (services, network topologies, ports) and TECHNICAL_DOCUMENTATION.md in the repository root.

Sibling architecture guide: architecture and MCP surface.