Skip to content
RightCapital Knowledge Base

Integration Architecture

Integration architecture consists of two main patterns based on how data is transferred from Vendors:

  1. File-based - Vendor pushes files via SFTP, processed by Collector
  2. API-based - RightCapital calls Vendor APIs directly

Both patterns ultimately store data in RightCapital’s database and are synchronized nightly.

File-based Integration Architecture

Section titled “File-based Integration Architecture”
flowchart LR
    subgraph Vendor
        VS[Vendor SFTP Server]
    end

    subgraph RightCapital
        C[Collector]
        S3[(S3 Bucket)]
        RA[Retail API]
        DB[(Database)]
    end

    VS -->|SFTP Download| C
    C -->|Upload| S3
    S3 -->|Read & Parse| RA
    RA -->|Save| DB

Data Flow

Section titled “Data Flow”
  1. Vendor generates data files (daily) containing advisor’s client data
  2. Collector connects to Vendor SFTP, downloads new files
  3. Collector processes files (decompress, organize) and uploads to S3
  4. Retail API reads files from S3, parses content using integrations-file-based library
  5. Database stores the parsed data under the appropriate advisor/household

Key Components

Section titled “Key Components”
ComponentRepositoryResponsibility
Collectorintegrations/collectorDownload, process, upload files
integrations-file-basedphp-libs/packages/libs/integrations-file-basedParse vendor file formats
Retail APIweb-service/apiOrchestrate sync, save to DB

API-based Integration Architecture

Section titled “API-based Integration Architecture”
flowchart LR
    subgraph Vendor
        VA[Vendor API]
    end

    subgraph RightCapital
        RA[Retail API]
        DB[(Database)]
    end

    RA -->|API Call with Auth Token| VA
    VA -->|Response Data| RA
    RA -->|Save| DB

Data Flow

Section titled “Data Flow”
  1. Advisor authorizes RightCapital to access their Vendor data (OAuth flow)
  2. Retail API stores authorization credentials
  3. Retail API calls Vendor API using stored credentials
  4. Response data is parsed and saved to database

Key Components

Section titled “Key Components”
ComponentLocationResponsibility
Integrations Moduleapi/app/Integrations/Vendor-specific API clients
OAuth Controllersapi/app/Http/Controllers/Handle authorization flows

Nightly Sync Process

Section titled “Nightly Sync Process”

Both File-based and API-based integrations are synchronized through the Nightly Sync process:

sequenceDiagram
    participant Scheduler
    participant Command
    participant Queue
    participant Worker
    participant VendorAPI as Vendor API/S3
    participant DB

    Scheduler->>Command: Trigger nightly sync
    Command->>DB: Get all integration mappings
    Command->>Queue: Create batch jobs (per mapping)
    Queue->>Worker: Process jobs
    Worker->>VendorAPI: Fetch latest data
    VendorAPI-->>Worker: Return data
    Worker->>DB: Update records

Sync Flow

Section titled “Sync Flow”
  1. Scheduler triggers sync command (US evening, after market close)
  2. Command queries all active integration mappings
  3. Queue receives batch jobs for each mapping
  4. Worker processes each job:
    • File-based: Read latest files from S3
    • API-based: Call Vendor API with stored credentials
  5. Database is updated with fresh data

Timing

Section titled “Timing”
  • Runs daily on US business days
  • Scheduled after US market close to capture end-of-day data
  • Different vendors may have different file delivery times

SSO Architecture

Section titled “SSO Architecture”
flowchart LR
    subgraph Vendor
        VP[Vendor Portal]
    end

    subgraph RightCapital
        SSO[SSO Controller]
        Auth[Auth Service]
        App[Application]
    end

    VP -->|SSO Request + Token| SSO
    SSO -->|Validate| Auth
    Auth -->|Create Session| App

SSO Types

Section titled “SSO Types”
DirectionDescriptionCommon Use
Vendor → RCAdvisor logs into RightCapital from Vendor systemMost common
RC → VendorAdvisor logs into Vendor from RightCapitalLess common
Contextual SSOSSO with household context (auto-link data)Premium feature

SSO Code Location

Section titled “SSO Code Location”
  • Controllers: api/app/Http/Controllers/Sso/
  • Each Vendor has a dedicated SSO handler

Monitoring

Section titled “Monitoring”

Integration processes are monitored for:

  • File arrival - Did Vendor deliver files on time?
  • Sync completion - Did all mappings sync successfully?
  • Error rates - API failures, parsing errors
  • Data freshness - Is data up-to-date?

See: [Nightly Sync & Monitoring](../../operations/nightly-sync/

Source

Section titled “Source”