# marahamj/client-onboarding-pipeline- architecture

> Architecture diagram of the GitHub repository marahamj/client-onboarding-pipeline-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marahamj/client-onboarding-pipeline-
- Repository: https://github.com/marahamj/client-onboarding-pipeline-

## Overview

This is a CRM-triggered client-onboarding backend: a Deal Won webhook creates a client/onboarding record and seven persisted steps, which can then be run or resumed through the API. The orchestrator claims each step, invokes a mock provider with retries, and records success or failure for recovery. A Streamlit dashboard monitors onboardings and the dead-letter queue through the API. Provider integrations are mocked; relationships below are based on the README and excerpted source, not unsampled implementation.

Main entry points: [`app/services/orchestrator.py`](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/orchestrator.py) (Step orchestrator), [`app/main.py`](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/main.py) (FastAPI endpoints), [`app/models.py`](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/models.py) (PostgreSQL state), [`app/services/idempotency.py`](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/idempotency.py) (Step claiming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and intake"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_payload["Webhook schemas<br/>[schemas.py]"]
end

subgraph group_workflow["Workflow execution"]
  node_workflow["Seven-step onboarding<br/>[constants.py]"]
  node_orchestrator["Step orchestrator<br/>[orchestrator.py]"]
  node_retry["Retry policy<br/>[orchestrator.py]"]
  node_provider["Mock provider<br/>[mock_provider.py]"]
end

subgraph group_state["Persistence and recovery"]
  node_idempotency["Step claiming<br/>[idempotency.py]"]
  node_database[("PostgreSQL state<br/>[models.py]")]
  node_dlq["Dead-letter handling<br/>[dlq_service.py]"]
  node_alert["Supervisor logging<br/>[alerting.py]"]
end

subgraph group_monitor["Monitoring"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
end

node_crm(("CRM deal event"))

node_crm -->|"sends webhook"| node_api
node_api -->|"validates payload"| node_payload
node_api -->|"creates and reads"| node_database
node_api -->|"starts or runs"| node_orchestrator
node_orchestrator -->|"iterates steps"| node_workflow
node_orchestrator -->|"claims and updates"| node_idempotency
node_orchestrator -->|"executes with retries"| node_retry
node_retry -->|"calls provider"| node_provider
node_orchestrator -->|"receives result"| node_provider
node_idempotency -->|"locks and persists"| node_database
node_orchestrator -->|"reads and updates"| node_database
node_orchestrator -->|"records or resolves"| node_dlq
node_dlq -->|"persists events"| node_database
node_orchestrator -->|"logs failure alert"| node_alert
node_dashboard -->|"requests status"| node_api

click node_api "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/main.py"
click node_payload "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/schemas.py"
click node_workflow "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/constants.py"
click node_orchestrator "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/orchestrator.py"
click node_retry "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/orchestrator.py"
click node_provider "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/mock_provider.py"
click node_idempotency "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/idempotency.py"
click node_database "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/models.py"
click node_dlq "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/dlq_service.py"
click node_alert "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/alerting.py"
click node_dashboard "https://github.com/marahamj/client-onboarding-pipeline-/blob/main/dashboard/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_payload toneBlue
class node_workflow,node_orchestrator,node_retry,node_provider toneAmber
class node_idempotency,node_database,node_dlq,node_alert toneMint
class node_dashboard toneRose
class node_crm toneIndigo
```

## Components

### API and intake

- [FastAPI endpoints](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/main.py): `app/main.py`
- [Webhook schemas](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/schemas.py): `app/schemas.py`

### Workflow execution

- [Seven-step onboarding](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/constants.py): `app/constants.py`
- [Step orchestrator](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/orchestrator.py): `app/services/orchestrator.py`
- [Retry policy](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/orchestrator.py): `app/services/orchestrator.py`
- [Mock provider](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/mock_provider.py): `app/services/mock_provider.py`

### Persistence and recovery

- [Step claiming](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/idempotency.py): `app/services/idempotency.py`
- [PostgreSQL state](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/models.py): `app/models.py`
- [Dead-letter handling](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/dlq_service.py): `app/services/dlq_service.py`
- [Supervisor logging](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/app/services/alerting.py): `app/services/alerting.py`

### Monitoring

- [Streamlit dashboard](https://github.com/marahamj/client-onboarding-pipeline-/blob/main/dashboard/app.py): `dashboard/app.py`

### Other components

- **CRM deal event**

## Connections

- CRM deal event → FastAPI endpoints: sends webhook (evidence: `README.md`)
- FastAPI endpoints → Webhook schemas: validates payload (evidence: `app/main.py`)
- FastAPI endpoints → PostgreSQL state: creates and reads (evidence: `app/main.py`)
- FastAPI endpoints → Step orchestrator: starts or runs (evidence: `app/main.py`)
- Step orchestrator → Seven-step onboarding: iterates steps (evidence: `app/services/orchestrator.py`)
- Step orchestrator → Step claiming: claims and updates (evidence: `app/services/orchestrator.py`)
- Step orchestrator → Retry policy: executes with retries (evidence: `app/services/orchestrator.py`)
- Retry policy → Mock provider: calls provider (evidence: `app/services/orchestrator.py`)
- Step orchestrator → Mock provider: receives result (evidence: `app/services/orchestrator.py`)
- Step claiming → PostgreSQL state: locks and persists (evidence: `app/services/idempotency.py`)
- Step orchestrator → PostgreSQL state: reads and updates (evidence: `app/services/orchestrator.py`)
- Step orchestrator → Dead-letter handling: records or resolves (evidence: `app/services/orchestrator.py`)
- Dead-letter handling → PostgreSQL state: persists events (evidence: `app/services/dlq_service.py`)
- Step orchestrator → Supervisor logging: logs failure alert (evidence: `app/services/orchestrator.py`)
- Streamlit dashboard → FastAPI endpoints: requests status (evidence: `dashboard/app.py`)