# paritoshsrivastava31/instagram-outreach-os architecture

> Architecture diagram of the GitHub repository paritoshsrivastava31/instagram-outreach-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paritoshsrivastava31/instagram-outreach-os
- Repository: https://github.com/paritoshsrivastava31/instagram-outreach-os

## Overview

Instagram Outreach OS is an internal founder dashboard for finding and qualifying Instagram prospects, preparing deterministic messages, and managing manual outreach through adoption outcomes. Its main workflow is discovery → qualification/scoring and deduplication → queued leads and prepared message → founder-reviewed Instagram contact → reply and funnel tracking. The API routes own orchestration; shared libraries provide scoring, templates, provider selection, persistence, and cost controls. README capabilities guide inclusion of analytics, campaigns, templates, settings, and webhook tracking; those unsampled UI details are represented at their exact tree paths, with only documented relationships asserted.

Main entry points: [`src/lib/db.ts`](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/db.ts) (Data access), [`src/app/api/discovery/run/route.ts`](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/discovery/run/route.ts) (Discovery orchestration), [`src/app/api/discovery/recover-last-run/route.ts`](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/discovery/recover-last-run/route.ts) (Run recovery), [`src/lib/discovery/index.ts`](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/index.ts) (Provider selector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Prospect discovery"]
  node_discovery_ui["Discovery workspace<br/>[page.tsx]"]
  node_discovery_run["Discovery orchestration<br/>[route.ts]"]
  node_recovery["Run recovery<br/>[route.ts]"]
  node_scorer["Lead scoring<br/>[scorer.ts]"]
  node_taxonomy["Qualification taxonomy<br/>[taxonomy.ts]"]
  node_provider_selector["Provider selector<br/>[index.ts]"]
  node_provider_contract["Provider contract"]
  node_apify["Apify provider<br/>[apify-provider.ts]"]
  node_mock["Sandbox provider<br/>[mock-provider.ts]"]
  node_cost["Cost guardrails<br/>[cost-control.ts]"]
end

subgraph group_outreach["Outreach operations"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_leads_ui["Lead workspace<br/>[page.tsx]"]
  node_lead_api["Lead actions"]
  node_message_logic["Message templates<br/>[messaging.ts]"]
  node_webhook["Reply webhook<br/>[route.ts]"]
  node_funnel["Adoption funnel<br/>[route.ts]"]
end

subgraph group_operations["Campaign operations"]
  node_campaign_ui["Campaign manager<br/>[page.tsx]"]
  node_campaign_api["Campaign API<br/>[route.ts]"]
  node_templates_ui["Template manager<br/>[page.tsx]"]
  node_settings_ui["Settings<br/>[page.tsx]"]
  node_settings_api["Settings API<br/>[route.ts]"]
  node_analytics_ui["Analytics<br/>[page.tsx]"]
  node_analytics_api["Analytics API<br/>[route.ts]"]
end

subgraph group_platform["Application services"]
  node_auth["Admin authentication<br/>[auth.ts]"]
  node_login_api["Login endpoint<br/>[route.ts]"]
  node_logout_api["Logout endpoint<br/>[route.ts]"]
  node_middleware["Route protection<br/>[middleware.ts]"]
  node_db_layer["Data access<br/>[db.ts]"]
  node_supabase["Supabase client<br/>[supabase.ts]"]
end

node_founder(("Founder"))
node_instagram(("Instagram"))
node_database[("Supabase database")]

node_founder -->|"starts discovery"| node_discovery_ui
node_discovery_ui -.->|"requests run"| node_discovery_run
node_discovery_run -->|"selects provider"| node_provider_selector
node_provider_selector -->|"selects Apify"| node_apify
node_provider_selector -->|"selects sandbox"| node_mock
node_apify -->|"implements"| node_provider_contract
node_mock -->|"implements"| node_provider_contract
node_discovery_run -->|"checks budget"| node_cost
node_discovery_run -->|"scores profiles"| node_scorer
node_scorer -->|"uses categories"| node_taxonomy
node_discovery_run -->|"prepares message"| node_message_logic
node_discovery_run -->|"reads and saves"| node_db_layer
node_recovery -->|"scores profiles"| node_scorer
node_recovery -->|"prepares message"| node_message_logic
node_recovery -->|"saves recovered leads"| node_db_layer
node_leads_ui -.->|"manages leads"| node_lead_api
node_lead_api -->|"updates lead state"| node_db_layer
node_founder -->|"sends manually"| node_instagram
node_instagram -->|"delivers reply event"| node_webhook
node_webhook -->|"updates reply status"| node_db_layer
node_founder -->|"tracks adoption"| node_funnel
node_funnel -->|"records stage"| node_db_layer
node_campaign_ui -.->|"manages campaigns"| node_campaign_api
node_campaign_api -->|"reads and writes"| node_db_layer
node_templates_ui -.->|"manages templates"| node_db_layer
node_settings_ui -.->|"configures sender"| node_settings_api
node_settings_api -->|"reads and updates"| node_db_layer
node_settings_api -->|"checks health"| node_supabase
node_analytics_ui -.->|"requests metrics"| node_analytics_api
node_analytics_api -->|"reads metrics"| node_db_layer
node_login_api -->|"checks credentials"| node_auth
node_logout_api -->|"clears session"| node_auth
node_middleware -->|"validates session"| node_auth
node_db_layer -->|"uses clients"| node_supabase
node_supabase -->|"reads and writes"| node_database

click node_dashboard "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/page.tsx"
click node_leads_ui "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/leads/page.tsx"
click node_lead_api "https://github.com/paritoshsrivastava31/instagram-outreach-os/tree/main/src/app/api/leads"
click node_message_logic "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/messaging.ts"
click node_webhook "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/webhooks/instagram/route.ts"
click node_funnel "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/leads/%5Bid%5D/funnel/route.ts"
click node_discovery_ui "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/discovery/page.tsx"
click node_discovery_run "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/discovery/run/route.ts"
click node_recovery "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/discovery/recover-last-run/route.ts"
click node_scorer "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/scorer.ts"
click node_taxonomy "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/taxonomy.ts"
click node_provider_selector "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/index.ts"
click node_provider_contract "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/provider.interface.ts"
click node_apify "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/apify-provider.ts"
click node_mock "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/mock-provider.ts"
click node_cost "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/cost-control.ts"
click node_campaign_ui "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/campaigns/page.tsx"
click node_campaign_api "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/campaigns/route.ts"
click node_templates_ui "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/templates/page.tsx"
click node_settings_ui "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/settings/page.tsx"
click node_settings_api "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/settings/route.ts"
click node_analytics_ui "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/analytics/page.tsx"
click node_analytics_api "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/analytics/route.ts"
click node_auth "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/auth.ts"
click node_login_api "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/auth/login/route.ts"
click node_logout_api "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/auth/logout/route.ts"
click node_middleware "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/middleware.ts"
click node_db_layer "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/db.ts"
click node_supabase "https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/supabase.ts"

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_discovery_ui,node_discovery_run,node_recovery,node_scorer,node_taxonomy,node_provider_selector,node_provider_contract,node_apify,node_mock,node_cost toneBlue
class node_dashboard,node_leads_ui,node_lead_api,node_message_logic,node_webhook,node_funnel,node_database toneAmber
class node_campaign_ui,node_campaign_api,node_templates_ui,node_settings_ui,node_settings_api,node_analytics_ui,node_analytics_api toneMint
class node_auth,node_login_api,node_logout_api,node_middleware,node_db_layer,node_supabase toneRose
class node_founder,node_instagram toneIndigo
```

## Components

### Prospect discovery

- [Discovery workspace](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/discovery/page.tsx): `src/app/discovery/page.tsx`
- [Discovery orchestration](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/discovery/run/route.ts): `src/app/api/discovery/run/route.ts`
- [Run recovery](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/discovery/recover-last-run/route.ts): `src/app/api/discovery/recover-last-run/route.ts`
- [Lead scoring](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/scorer.ts): `src/lib/scorer.ts`
- [Qualification taxonomy](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/taxonomy.ts): `src/lib/taxonomy.ts`
- [Provider selector](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/index.ts): `src/lib/discovery/index.ts`
- [Provider contract](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/provider.interface.ts): `src/lib/discovery/provider.interface.ts`
- [Apify provider](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/apify-provider.ts): `src/lib/discovery/apify-provider.ts`
- [Sandbox provider](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/discovery/mock-provider.ts): `src/lib/discovery/mock-provider.ts`
- [Cost guardrails](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/cost-control.ts): `src/lib/cost-control.ts`

### Outreach operations

- [Dashboard](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Lead workspace](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/leads/page.tsx): `src/app/leads/page.tsx`
- [Lead actions](https://github.com/paritoshsrivastava31/instagram-outreach-os/tree/main/src/app/api/leads): `src/app/api/leads`
- [Message templates](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/messaging.ts): `src/lib/messaging.ts`
- [Reply webhook](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/webhooks/instagram/route.ts): `src/app/api/webhooks/instagram/route.ts`
- [Adoption funnel](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/leads/%5Bid%5D/funnel/route.ts): `src/app/api/leads/[id]/funnel/route.ts`

### Campaign operations

- [Campaign manager](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/campaigns/page.tsx): `src/app/campaigns/page.tsx`
- [Campaign API](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/campaigns/route.ts): `src/app/api/campaigns/route.ts`
- [Template manager](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/templates/page.tsx): `src/app/templates/page.tsx`
- [Settings](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/settings/page.tsx): `src/app/settings/page.tsx`
- [Settings API](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/settings/route.ts): `src/app/api/settings/route.ts`
- [Analytics](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/analytics/page.tsx): `src/app/analytics/page.tsx`
- [Analytics API](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/analytics/route.ts): `src/app/api/analytics/route.ts`

### Application services

- [Admin authentication](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Login endpoint](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/auth/login/route.ts): `src/app/api/auth/login/route.ts`
- [Logout endpoint](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/app/api/auth/logout/route.ts): `src/app/api/auth/logout/route.ts`
- [Route protection](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/middleware.ts): `src/middleware.ts`
- [Data access](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Supabase client](https://github.com/paritoshsrivastava31/instagram-outreach-os/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`

### Other components

- **Founder**
- **Instagram**
- **Supabase database**

## Connections

- Founder → Discovery workspace: starts discovery
- Discovery workspace → Discovery orchestration: requests run
- Discovery orchestration → Provider selector: selects provider (evidence: `src/app/api/discovery/run/route.ts`)
- Provider selector → Apify provider: selects Apify (evidence: `src/lib/discovery/index.ts`)
- Provider selector → Sandbox provider: selects sandbox (evidence: `src/lib/discovery/index.ts`)
- Apify provider → Provider contract: implements (evidence: `src/lib/discovery/apify-provider.ts`)
- Sandbox provider → Provider contract: implements (evidence: `src/lib/discovery/mock-provider.ts`)
- Discovery orchestration → Cost guardrails: checks budget (evidence: `src/app/api/discovery/run/route.ts`)
- Discovery orchestration → Lead scoring: scores profiles (evidence: `src/app/api/discovery/run/route.ts`)
- Lead scoring → Qualification taxonomy: uses categories (evidence: `src/lib/scorer.ts`)
- Discovery orchestration → Message templates: prepares message (evidence: `src/app/api/discovery/run/route.ts`)
- Discovery orchestration → Data access: reads and saves (evidence: `src/app/api/discovery/run/route.ts`)
- Run recovery → Lead scoring: scores profiles (evidence: `src/app/api/discovery/recover-last-run/route.ts`)
- Run recovery → Message templates: prepares message (evidence: `src/app/api/discovery/recover-last-run/route.ts`)
- Run recovery → Data access: saves recovered leads (evidence: `src/app/api/discovery/recover-last-run/route.ts`)
- Lead workspace → Lead actions: manages leads
- Lead actions → Data access: updates lead state (evidence: `src/app/api/leads/route.ts`)
- Founder → Instagram: sends manually
- Instagram → Reply webhook: delivers reply event
- Reply webhook → Data access: updates reply status (evidence: `src/app/api/webhooks/instagram/route.ts`)
- Founder → Adoption funnel: tracks adoption
- Adoption funnel → Data access: records stage (evidence: `src/app/api/leads/[id]/funnel/route.ts`)
- Campaign manager → Campaign API: manages campaigns
- Campaign API → Data access: reads and writes (evidence: `src/app/api/campaigns/route.ts`)
- Template manager → Data access: manages templates
- Settings → Settings API: configures sender
- Settings API → Data access: reads and updates (evidence: `src/app/api/settings/route.ts`)
- Settings API → Supabase client: checks health (evidence: `src/app/api/settings/route.ts`)
- Analytics → Analytics API: requests metrics
- Analytics API → Data access: reads metrics (evidence: `src/app/api/analytics/route.ts`)
- Login endpoint → Admin authentication: checks credentials (evidence: `src/app/api/auth/login/route.ts`)
- Logout endpoint → Admin authentication: clears session (evidence: `src/app/api/auth/logout/route.ts`)
- Route protection → Admin authentication: validates session (evidence: `src/middleware.ts`)
- Data access → Supabase client: uses clients (evidence: `src/lib/db.ts`)
- Supabase client → Supabase database: reads and writes (evidence: `src/lib/supabase.ts`)
