Integration Team Onboarding

This guide provides a structured learning path for new team members joining the Integration Team. Work through each section sequentially, using the questions as self-assessment checkpoints.

Prerequisites

Before diving into Integration-specific topics:

1. Complete general RightCapital onboarding
2. Set up local development environment
3. Get access to relevant GitLab repositories
4. Get Admin Center access (QA environment)

Learning Path

Phase 1: Foundations

Goal: Understand what Integration Team does and why it matters.

Task	Resource
Read Integration overview	[Overview](overview/
Understand architecture	[Architecture](architecture/
Watch Integration videos	Notion: Integration Videos

Self-check questions:

• What is the business value of integrations for advisors?
• What are the main types of integrations (Data, SSO, CRM)?
• What is the difference between File-based and API-based integrations?

Phase 2: Collector

Goal: Understand how file-based data flows into the system.

Task	Resource
Read Collector documentation	[Collector](../../components/collector/
Explore Collector codebase	GitLab: Collector

Self-check questions:

• What is the purpose of Collector?
• How does Collector communicate with Vendors (SFTP, etc.)?
• What are the 4 processing stages (Downloader, Processor, Uploader, Finalizer)?
• What does each stage do?
• What is the final output (LATEST files on S3)?

Phase 3: API-based Integration

Goal: Understand how API integrations work.

Task	Resource
Read API integrations doc	[API Integrations](../../components/api-integrations/
Explore Integrations codebase	GitLab: app/Integrations

Self-check questions:

• How do we establish connection with Vendors (OAuth, API key, etc.)?
• What is the Connector/Integrator/Request architecture?
• How does API integration fetch Vendor data?
• What data do we typically fetch (households, accounts, positions)?
• How is Vendor data linked to RightCapital households?
• What does IntegrationConfigController do?
• What does IntegrationImportController do?

Phase 4: File-based Integration

Goal: Understand how file integrations work.

Task	Resource
Read File integrations doc	[File Integrations](../../components/file-integrations/
Explore integrations-file-based lib	GitLab: integrations-file-based

Self-check questions:

• Where does the Vendor data come from (S3 via Collector)?
• What data is typically in the files (accounts, positions, securities)?
• How is file data linked to RightCapital households?

Phase 5: Sync Process

Goal: Understand the nightly sync mechanism.

Task	Resource
Read Nightly Sync doc	[Nightly Sync](../../operations/nightly-sync/

Self-check questions:

• What is Sync in one sentence?
• What data gets synced?
• What is a Holding?
• How are Holdings synchronized?
• What are the different types of Holdings?

Phase 6: Database Schema

Goal: Understand the data model.

Key tables to study:

Table	Purpose
integrations	Advisor’s connection to a Vendor
integration_mappings	Links between Vendor entities and RC entities

Self-check questions:

• What does a row in integrations represent?
• What is the reference field in integrations?
• What is the difference between credentials and reference?
• What does integration_mappings represent?
• What is the reference field in integration_mappings?
• What does parent_id being null vs non-null mean?
• What are the different mappable_type values and their meanings?

Phase 7: SSO

Goal: Understand Single Sign-On integration.

Task	Resource
Read SSO doc	[SSO](../../components/sso/
Explore SSO controllers	GitLab: app/Http/Controllers/Sso

Self-check questions:

• What is a Service Provider (SP)?
• What is an Identity Provider (IdP)?
• What is IdP-initiated SSO flow?
• What is SP-initiated SSO flow?
• How is a SAML Response validated?
• What fields are validated in a SAML Response?

Hands-on Practice

After completing the reading, try these practical exercises:

1. Trace a File-based sync: Follow data from S3 → Retail API → Database
2. Trace an API-based sync: Follow an OAuth flow → API call → Database save
3. Debug a Data Issue: Use Admin Center to view integration logs
4. Read Vendor files: Download a file from S3 and understand its structure

Getting Help

• Slack: #integration-team channel
• Documentation: This knowledge base + Notion
• Pair programming: Shadow a team member on a real task

Source

• Notion: Integration Team Onboarding