Skip to main content

PMS Sync is currently in a pilot programme; capabilities described here are live in pilot deployments.

Deployment Topology

Deployment Topology

Last updated Owner: AlterspectiveFor: Solution architects & client IT

Who installs what, and where. PMS Sync spans three ownership zones: what we install at the client, what we host, and what we deploy into the client's Sharedo / Clio tenant. Aderant Expert has no OAuth (NTLM only), so a proxy must sit on the client network — that is the whole reason the client-side install exists.

Installed in client environment Hosted & run by Alterspective Deployed into Sharedo / Clio
Client environment

Installed on-premise

We install on the client network · outbound-only

Aderant Expert

client's system

The firm's practice-management system — SQL Server database plus REST APIs behind NTLM (no OAuth, so it cannot be called from the cloud directly). The source of truth we read matters, clients, and employees from.

Aderant SQL API agent

read

AderantSQLAPITypeScript · :4102

Our agent that queries the Aderant SQL Server (clients, matters, employees, table/view reads). Ships as a Windows service (MSI / WinSW) or Docker. The read engine behind every lookup and duplicate-check.

Aderant REST / CRUD proxy

Phase 2

aderant-rest-api

NTLM proxy wrapping Aderant Expert REST APIs so the cloud can call them as the correct account. Needed for write-back into Aderant. Phase 2 — not yet stood up.

Outbound tunnel

Azure Relay (preferred) · or ngrok

Outbound-only connection that lets the hosted proxy reach the on-prem agent — no inbound firewall ports. Azure Relay is the client-friendly default; ngrok for short pilots.

Alterspective

Hosted services

We host & run · Coolify / shared platform · multi-tenant

API Proxy / Orchestrator

read + write

ShareDoAderantAPIProxy · :3050 · aderant-proxy.alterspective.com.au

The brain. The single backend the portal and Sharedo call. Resolves per-org config, reaches the on-prem agent over the tunnel, writes matters and parties into Clio Operate, runs reconcile, and mints the embed JWT. Serves /api/v1/* (legacy /api/* alias).

Import Portal

AderantImportPortal · pms-sync.alterspective.com.au

The human UI — search a matter, preview, map work-types and participant roles, resolve duplicates, import, review history, and manage per-org settings. Calls only the API Proxy for Aderant / Clio data.

Keystone — identity

shared

identity.alterspective.com.au · OIDC

Login and organisation resolution for the portal; OAuth for the backend MCP surfaces. Fails closed.

Supabase — config & history

shared

Stores each organisation's connection config (tunnel URL and keys, Clio credentials, mappings) and the import audit history.

Synapse (GpuAsAService) — AI mapping

synapse-api.alterspective.com.au

In-house GPU inference for AI mapping authoring (MAP-001). Optional; disabled when no key is set.

Sharedo / Clio

Into the client tenant

We deploy config + widgets into the client tenant

PMS Sync embed widget

Alt.Widgets.PmsSync.Embed

Hosts the Import Portal inside Sharedo via an iframe with signed-JWT SSO. Brokers portal-to-Sharedo API calls through the proxy convention; contributor/audit stamping depends on the embedded path passing user claims through to the proxy or routing writes through the portal API.

Linked Services (Service Connections)

aderant-import-proxy · aderant-sql-api

Sharedo's required outbound shared-secret connectors that point at our hosted proxy and the on-prem agent. The Phase 2 REST connector is optional until Aderant write-back is enabled. They inject the API key server-side; secrets never reach the browser.

Import page + widgets

"PMS Import" page · diagnostics in /Insight

The import surface hosts the PMS Sync embed and PMS Matter Import action. Operational diagnostics use the Insight widgets such as Monitor and DB Logs; legacy search widgets stay disabled until their proc-exec routes are updated.

Imported records

write

Matters · ODS parties · roles · attributes

The output — Aderant matters land as Sharedo work items with mapped clients, parties, case team, work-type, and stored Aderant IDs (matter / client UNO) for future two-way sync.

Tunnel: Hosted API Proxy ⇄ on-prem SQL agent (Azure Relay / ngrok)Embed: Sharedo widget ⇄ Portal iframe (signed JWT)Trace: x-correlation-id Portal → Proxy → SQL API

Request flow — importing a matter

  1. 1

    Login

    A Sharedo user opens the PMS Import page; the embed widget mints a short-lived JWT via the API Proxy's /api/embed/handoff and iframes the Portal (SSO — no second login).

  2. 2

    Find

    The user types an Aderant matter number. Portal calls GET /api/import/matters/search on the API Proxy.

  3. 3

    Reach on-prem

    The Proxy calls the on-prem SQL API agent across the Azure Relay / ngrok tunnel, which reads the live Aderant SQL Server.

  4. 4

    Preview & map

    POST /api/import/matter/{uno}/preview returns the mapped work-type, participants, duplicate warnings, and field mappings. Standalone portal calls attach the selected environment config and saved mappings; embedded pass-through must preserve the same environment and mapping payloads to be equivalent.

  5. 5

    Import

    POST /api/import/matter/{uno} — the Proxy writes the matter and ODS parties into Clio Operate via configured service credentials. Standalone portal imports can add the signed-in user as contributor; embedded imports need the Sharedo user claims passed through before promising contributor or user-audit stamps.

  6. 6

    Write-back (Phase 2)

    For create / update into Aderant, the Proxy calls the on-prem REST / CRUD proxy (NTLM).

  7. 7

    History & reconcile

    Standalone portal imports are logged to Supabase history. Embedded pass-through imports audit at the proxy today. Scheduled close-sync starts at the Portal /api/cron/run entrypoint, which calls the Proxy reconcile API with candidate matters.

  8. 8

    Config & auth

    Per-org connection and mappings live in Supabase. Keystone OIDC protects the standalone portal and MCP surfaces; the Sharedo embed uses a proxy-minted signed JWT exchanged by the portal.

Embedded parity checks. When the Portal is hosted inside Sharedo and calls are sent through Sharedo's /api/proxy/aderant-import-proxy path, confirm the proxy-side embedded config loader includes the tenant's Azure Relay key fields, preserves the selected environment_slug, and receives the same saved mapping documents that the standalone portal API attaches. Save-for-next-time mapping writes and Add-me/audit user stamps also require either routing those writes through the portal API or adding equivalent proxy-side persistence and user-claim propagation.
Per client install = the SQL API agent (plus the optional REST / CRUD proxy) on the Aderant box, one outbound tunnel, and the Sharedo-side bundle (embed widget + required linked services + the import page). The hosted Portal and Proxy are multi-tenant — one deployment serves every client; each tenant is isolated by its org config and the token's org claim.

For the matter-import flow in depth, see the Architecture page. For what the client's IT team must provide, see the Client Requirements Checklist. For step-by-step setup, see the Deployment Guide.