Skip to main content

Onboarding Guides

Role-based guides for getting up to speed with ComplyAI's data and systems

📋 Table of Contents​

  1. New Engineer Onboarding
  2. New Product Manager Onboarding
  3. New Data/Analytics Onboarding
  4. New Customer Success Onboarding
  5. New Leadership Onboarding

New Engineer Onboarding​

Week 1: Foundation​

Day 1-2: Environment Setup​

  • Get access to GitHub organization
  • Set up local development environment
    • Clone all service repositories
    • Install Docker Desktop
    • Configure environment variables
  • Get access to AWS Console (read-only initially)
  • Join Slack channels: #engineering, #alerts, #deployments
  • Get access to monitoring tools (CloudWatch, logs)

Day 3-4: Architecture Overview​

ServicePurposeKey Responsibility
complyai-coreCentral APIAuth, Users, Organizations
complyai-apiData APIAd accounts, Ad data processing
complyai-maestroML PipelineWebhooks, ML inference
complyai-violinAI ScoringCompliance scoring engine
complyai-triangleNotificationsUser notifications, Ad rules
complyai-frontendWeb AppReact user interface

Day 5: First Code​

  • Find a "good first issue" in GitHub
  • Make your first PR (even if small)
  • Get added to code review rotation

Week 2: Deep Dive​

Domain Understanding​

Service Deep Dive​

Pick one service to understand deeply:

  • Read the service's README
  • Trace a request from API to database
  • Understand the Celery tasks it uses
  • Review recent PRs to understand patterns

External Integrations​

Week 3-4: Contributing​

  • Take on a medium-sized feature/bug
  • Participate in code reviews
  • Shadow an on-call engineer for one rotation
  • Review Runbooks for operational procedures

Key Concepts for Engineers​

┌─────────────────────────────────────────────────────────────┐
│                     USER JOURNEY                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. User signs up (Auth0) ─────▶ users table                │
│                                                              │
│  2. User creates org ──────────▶ organizations table         │
│                                                              │
│  3. User connects Meta ────────▶ org_business_accounts       │
│     (OAuth flow)                                             │
│                                                              │
│  4. System syncs ad accounts ──▶ org_ad_accounts            │
│     (Every 15 min)                                           │
│                                                              │
│  5. System syncs ads ──────────▶ org_ads                    │
│     (Every 15 min)                                           │
│                                                              │
│  6. AI scores ads ─────────────▶ org_ads_score              │
│     (Every 30 min)                                           │
│                                                              │
│  7. User reviews flagged ads ──▶ User takes action          │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Common Development Tasks​

TaskWhere to LookKey Files
Add new API endpointcomplyai-core or complyai-apiroutes/*.py
Modify database schemacomplyai-coremigrations/
Change UI componentcomplyai-frontendsrc/components/
Add background jobService + celerytasks.py
Update ML modelcomplyai-violinmodels/
Add webhook handlercomplyai-maestrowebhooks/

New Product Manager Onboarding​

Week 1: Product Understanding​

Day 1-2: The Basics​

  • Create your own ComplyAI account (staging environment)
  • Connect a test Meta Business Manager
  • Experience the full user journey
  • Read Glossary for terminology

Day 3-5: Domain Knowledge​

  • Understand the four data domains:
DomainWhat It ContainsProduct Implications
CustomerUsers, Orgs, SubscriptionsAccount management, pricing
Ad ContentAd accounts, Ads, MediaCore feature set
ComplianceScores, Reviews, PoliciesDifferentiation, value prop
OperationalActivity, NotificationsUser experience
  • Read Quick Reference for status codes and common lookups
  • Understand Meta ad status lifecycle (Active → Disapproved → etc.)

Week 2: System Understanding​

How Data Flows​

  • Read Data Lineage - focus on business flow descriptions
  • Understand sync timing:
    • Ad sync: Every 15 minutes
    • Scoring: Every 30 minutes
    • Webhooks: Real-time (when received)

Feature Mapping​

FeatureServices InvolvedData Tables
User logincore, Auth0users
Dashboardfrontend, core, apiorganizations, org_ads
Ad reviewfrontend, api, violinorg_ads, org_ads_score
Notificationstriangle, frontendnotifications
Billingcore, Stripesubscriptions

Ongoing: Product Resources​

New Data/Analytics Onboarding​

Week 1: Data Landscape​

Day 1-2: Data Sources​

  • Get read-only database access (via bastion/BI tool)
  • Review Data Dictionary thoroughly
  • Understand primary data sources:
SourceWhat It ContainsHow to Access
PostgreSQL (prod)All application dataRead replica
BigQueryAnalytics warehouseDirect access
Meta APIAd performanceVia synced tables
StripePayment dataVia synced tables

Day 3-5: Data Modeling​

-- Core join pattern
SELECT 
    o.name as org_name,
    oaa.name as account_name,
    oa.name as ad_name,
    oas.overall_score
FROM organizations o
JOIN org_ad_accounts oaa ON o.id = oaa.organization_id
JOIN org_ads oa ON oaa.id = oa.org_ad_account_id
LEFT JOIN org_ads_score oas ON oa.id = oas.org_ad_id;

Week 2: Analysis Patterns​

Common Queries​

-- Active organizations
SELECT COUNT(DISTINCT organization_id) 
FROM org_ad_accounts 
WHERE is_connected = true;

-- Ads by status
SELECT complyai_status, COUNT(*) 
FROM org_ads 
GROUP BY complyai_status;

-- Score distribution
SELECT 
    CASE 
        WHEN overall_score >= 90 THEN 'Low Risk'
        WHEN overall_score >= 70 THEN 'Medium Risk'
        WHEN overall_score >= 50 THEN 'High Risk'
        ELSE 'Critical'
    END as risk_level,
    COUNT(*)
FROM org_ads_score
GROUP BY 1;

Data Quality Awareness​

  • Read Data Governance for quality standards
  • Understand data freshness expectations:
    • Ads: Updated every 15 min
    • Scores: Updated every 30 min
    • User data: Real-time

Key Tables for Analytics​

Use CasePrimary TablesNotes
User metricsusers, organizationsFilter is_active
Ad volumeorg_ads, org_ad_accountsJoin via org_ad_account_id
Compliance analysisorg_ads_score, org_adsLatest score per ad
Funnel analysisactivity_eventsaction column for events
Revenuesubscriptions, organizationsstripe_subscription_id

New Customer Success Onboarding​

Week 1: Platform Knowledge​

Day 1-2: User Experience​

  • Create staging account and full setup
  • Experience common user workflows:
    • Account creation
    • Meta connection (OAuth)
    • Ad review process
    • Notification handling

Day 3-5: Understanding Data​

  • Read Glossary for customer-facing terms
  • Study Quick Reference for:
    • Ad status meanings
    • Score interpretations
    • Common error codes

Key Customer Concepts​

Ad Status Lifecycle​

                    ┌─────────────┐
                    │   ACTIVE    │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
        ┌───────────┐           ┌───────────────┐
        │  PAUSED   │           │  DISAPPROVED  │
        └───────────┘           └───────┬───────┘
                                        │
                                        ▼
                                ┌───────────────┐
                                │   APPEALED    │
                                └───────┬───────┘
                                        │
                        ┌───────────────┴───────────────┐
                        ▼                               ▼
                ┌───────────────┐               ┌───────────────┐
                │  APPEAL WON   │               │  APPEAL LOST  │
                └───────────────┘               └───────────────┘

Score Interpretation Guide​

Score RangeRisk LevelWhat to Tell Customer
90-100Low"Your ad looks compliant"
70-89Medium"Minor issues detected - review recommended"
50-69High"Significant issues - edits strongly recommended"
0-49Critical"High risk of disapproval - action required"

Common Customer Questions​

QuestionWhere to Find Answer
"Why is my ad disapproved?"org_ads.effective_status + facebook_ad_status
"When did this happen?"activity_events with ad_id filter
"What's wrong with my ad?"org_ads_score (text_score, media_score, etc.)
"How do I reconnect?"OAuth flow - guide through Settings

New Leadership Onboarding​

Week 1: Strategic Overview​

Day 1-2: Platform Understanding​

  • Read main README for system overview
  • Understand the four data domains and their business value
  • Review Service Architecture at high level

Day 3-5: Governance & Compliance​

  • Read Data Governance thoroughly
  • Understand:
    • Data ownership model
    • Privacy compliance (GDPR, CCPA)
    • Incident response procedures

Key Metrics to Understand​

MetricSourceBusiness Meaning
Active Organizationsorganizations + subscriptionsPaying customers
Connected Accountsorg_ad_accountsPlatform adoption depth
Ads Monitoredorg_adsPlatform scale
Compliance Scoresorg_ads_scoreCore value delivery
User Engagementactivity_eventsPlatform stickiness

Platform Dependencies​

External ServiceBusiness Impact if DownSLA Target
Meta Graph APICore functionality unavailable99.9%
StripeBilling interrupted99.99%
Auth0Login unavailable99.99%
AWSFull platform outage99.9%

Reporting & Dashboards​

  • Operational Dashboard: Real-time system health
  • Business Dashboard: Customer metrics, revenue, growth
  • Compliance Dashboard: Data quality, privacy metrics

Onboarding Resources Summary​

All Roles Should Read​

DocumentWhy
GlossaryCommon vocabulary
Quick ReferenceFast lookups
Main READMEPlatform overview

Role-Specific Priority Reading​

RolePriority Documents
EngineerService Architecture, API Docs, Data Lineage
ProductData Dictionary, Entity Relationships, Quick Reference
Data/AnalyticsData Dictionary, Data Lineage, Data Governance
Customer SuccessGlossary, Quick Reference, Troubleshooting
LeadershipData Governance, Service Architecture

Getting Help​

Question TypeWhere to Ask
Technical/engineering#engineering Slack
Data questions#data-team Slack
Customer issues#customer-success Slack
This documentationSubmit PR or post in #data-team

Onboarding Feedback​

We want to improve! After your first month, please share:

  • What was missing from this guide?
  • What took longer than expected to understand?
  • What would have helped you ramp faster?

Submit feedback via PR to this document or message in #onboarding Slack.

Last Updated: December 2024