Skip to main content

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

Technical Overview

System Architecture & Deployment

Last updated Owner: AlterspectiveFor: Technical evaluators

This document provides a holistic technical overview of PMS Sync — the integration between Aderant Expert and Clio Operate (built on the Sharedo platform). It details the component architecture, data flow, security models, and deployment strategies utilized across the ecosystem.

1. Component Architecture

The integration is a multi-tier architecture designed to securely bridge an on-premise Aderant Expert SQL database with the cloud-hosted Clio Operate environment.

A. Aderant Import Portal (Frontend)

Tech Stack: Next.js 15 (App Router), React, TailwindCSS.

Provides the staff-facing interface for searching and triggering matter imports. It integrates with Alterspective Keystone (OIDC/Entra ID) for user SSO and utilizes Supabase for storing per-tenant configurations and logging historical import requests.

B. ShareDoAderantAPIProxy (Orchestration Layer)

Tech Stack: Node.js, Express, TypeScript.

Acts as the central orchestration middleware. It receives import requests from the Portal, queries the Aderant SQL API, transforms the data into the Sharedo schema, and executes the necessary mutations via the Sharedo REST API. It handles token exchange, caching, dry-run previews, and rate limiting.

C. Aderant SQL API (Data Layer)

Tech Stack: Node.js, Express, TypeScript, `mssql`.

A read-only REST API surface deployed adjacent to the Aderant SQL Server: it exposes table and view queries over GET only — there is no stored-procedure execution or other write path over HTTP — and a read-only SQL login (db_datareader) is the deployment standard, so database permissions are a second line of defence. It features connection pooling, auto-recovery, and dynamic query generation using parameterized SQL to prevent SQL injection. It also supports runtime schema discovery with automatic OpenAPI (Swagger) generation, served behind the API key.

D. Embedded Widget (Foundry SDK)

Tech Stack: Alterspective Foundry SDK.

Renders the Next.js portal within an iframe directly inside the Clio Operate portal. It uses the platform's service connection to acquire an embedded JWT payload and passes API calls via `postMessage` proxying to securely handle cross-origin bounds.

2. Data Flow & Integration Sequence

  1. Search: The Portal queries the API Proxy, which proxies the request to the Aderant SQL API. A mapped JSON list of matters is returned, with already-imported matters flagged.
  2. Preview: When a user clicks "Preview", the Proxy retrieves the full matter payload (including parties) from the SQL API. It simulates the entity creation and returns the proposed payload to the Portal, including candidate matches for each party and any applicable default teams.
  3. Execution: On "Execute", the Proxy connects to the Clio Operate API to:
    • Create ODS Parties, or link to existing ones as resolved by the user.
    • Create the Work Item (Matter), stamping the Aderant matter code and UNO for idempotency.
    • Attach Participants with mapped roles, and apply the configured default teams for matter security.

3. What's Shipped Today

  • Per-tenant mapping engine: work-type, field, and participant-role mappings configured per organisation and environment, with sandboxed JavaScript transforms, a live preview against real matters, starter templates, and export/import for backup.
  • Multi-environment support: each organisation can configure multiple target environments and switch between them in the portal.
  • Default teams (matter security): configured teams are added to every imported matter in a chosen role, per work type.
  • Import idempotency: re-importing a matter returns the existing work item (matched on matter reference and external reference) instead of creating a duplicate.
  • Close-sync reconciliation: matters closed in Aderant can be closed in Clio Operate — dry-run by default, with an optional schedule and Teams notifications.
  • Auto-import per client code: scheduled dry-run discovery of new matters for nominated clients, applied on demand by an administrator.
  • Audit & observability: every import attempt is recorded; an optional SIEM webhook exports audit events (CloudEvents 1.0); structured logs carry a correlation ID across portal → proxy → agent; Sentry error tracking runs in the portal and proxy.
  • MCP services: the proxy and the SQL agent each expose a Model Context Protocol endpoint (OAuth 2.1 via Keystone) with scope-gated read and write tools for AI-agent integration.

4. Security Posture

  • API Keys: `x-api-key` headers are required on every service-to-service call. In production, the on-premise agent refuses to start if its key is missing, shorter than 32 characters, or a placeholder.
  • CORS: origin whitelists are enforced at both the Proxy and the on-premise agent; unset means deny-all — there are no wildcard defaults.
  • No Direct Database Exposure: cloud components have zero direct network access to the on-premise Aderant SQL server; the agent is reached only via an outbound tunnel.
  • Authentication: all user sessions are authenticated via standard OIDC/Entra ID via Keystone, with organisation resolution failing closed.

5. Environment & Deployment

The repositories use CI/CD pipelines via GitHub Actions (typecheck, lint, unit tests, secret scanning) and are deployed to Alterspective's Coolify instance after green builds. Database schemas and audit logs are managed via Supabase. Real-time telemetry and error tracking are handled by Sentry across both the Portal and Proxy layers.