How paritoshsrivastava31/instagram-outreach-os works
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: db.ts Data access · run/route.ts Discovery orchestration · recover-last-run/route.ts Run recovery · index.ts Provider selector
Components 32
Prospect discovery
- Discovery workspace
src/app/discovery/page.tsx - Discovery orchestration
src/app/api/discovery/run/route.ts - Run recovery
src/app/api/discovery/recover-last-run/route.ts - Lead scoring
src/lib/scorer.ts - Qualification taxonomy
src/lib/taxonomy.ts - Provider selector
src/lib/discovery/index.ts - Provider contract
src/lib/discovery/provider.interface.ts - Apify provider
src/lib/discovery/apify-provider.ts - Sandbox provider
src/lib/discovery/mock-provider.ts - Cost guardrails
src/lib/cost-control.ts
Outreach operations
- Dashboard
src/app/page.tsx - Lead workspace
src/app/leads/page.tsx - Lead actions
src/app/api/leads - Message templates
src/lib/messaging.ts - Reply webhook
src/app/api/webhooks/instagram/route.ts - Adoption funnel
src/app/api/leads/[id]/funnel/route.ts
Campaign operations
- Campaign manager
src/app/campaigns/page.tsx - Campaign API
src/app/api/campaigns/route.ts - Template manager
src/app/templates/page.tsx - Settings
src/app/settings/page.tsx - Settings API
src/app/api/settings/route.ts - Analytics
src/app/analytics/page.tsx - Analytics API
src/app/api/analytics/route.ts
Application services
- Admin authentication
src/lib/auth.ts - Login endpoint
src/app/api/auth/login/route.ts - Logout endpoint
src/app/api/auth/logout/route.ts - Route protection
src/middleware.ts - Data access
src/lib/db.ts - Supabase client
src/lib/supabase.ts
Other components
- Founder
- Supabase database
Connections 35
- Founder → Discovery workspace: starts discovery
- Discovery workspace → Discovery orchestration: requests run
- Discovery orchestration → Provider selector: selects provider
src/app/api/discovery/run/route.ts - Provider selector → Apify provider: selects Apify
src/lib/discovery/index.ts - Provider selector → Sandbox provider: selects sandbox
src/lib/discovery/index.ts - Apify provider → Provider contract: implements
src/lib/discovery/apify-provider.ts - Sandbox provider → Provider contract: implements
src/lib/discovery/mock-provider.ts - Discovery orchestration → Cost guardrails: checks budget
src/app/api/discovery/run/route.ts - Discovery orchestration → Lead scoring: scores profiles
src/app/api/discovery/run/route.ts - Lead scoring → Qualification taxonomy: uses categories
src/lib/scorer.ts - Discovery orchestration → Message templates: prepares message
src/app/api/discovery/run/route.ts - Discovery orchestration → Data access: reads and saves
src/app/api/discovery/run/route.ts - Run recovery → Lead scoring: scores profiles
src/app/api/discovery/recover-last-run/route.ts - Run recovery → Message templates: prepares message
src/app/api/discovery/recover-last-run/route.ts - Run recovery → Data access: saves recovered leads
src/app/api/discovery/recover-last-run/route.ts - Lead workspace → Lead actions: manages leads
- Lead actions → Data access: updates lead state
src/app/api/leads/route.ts - Founder → Instagram: sends manually
- Instagram → Reply webhook: delivers reply event
- Reply webhook → Data access: updates reply status
src/app/api/webhooks/instagram/route.ts - Founder → Adoption funnel: tracks adoption
- Adoption funnel → Data access: records stage
src/app/api/leads/[id]/funnel/route.ts - Campaign manager → Campaign API: manages campaigns
- Campaign API → Data access: reads and writes
src/app/api/campaigns/route.ts - Template manager → Data access: manages templates
- Settings → Settings API: configures sender
- Settings API → Data access: reads and updates
src/app/api/settings/route.ts - Settings API → Supabase client: checks health
src/app/api/settings/route.ts - Analytics → Analytics API: requests metrics
- Analytics API → Data access: reads metrics
src/app/api/analytics/route.ts - Login endpoint → Admin authentication: checks credentials
src/app/api/auth/login/route.ts - Logout endpoint → Admin authentication: clears session
src/app/api/auth/logout/route.ts - Route protection → Admin authentication: validates session
src/middleware.ts - Data access → Supabase client: uses clients
src/lib/db.ts - Supabase client → Supabase database: reads and writes
src/lib/supabase.ts