# finbyz/finbyzreach architecture

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

- Interactive diagram: https://gitdiagram.com/finbyz/finbyzreach
- Repository: https://github.com/finbyz/finbyzreach

## Overview

Finbyzreach is a Frappe CRM outreach app combining scheduled AI-assisted stale-opportunity follow-ups with campaign broadcasting and a visual email-template editor. The main documented workflow evaluates stale records, enriches prospect context, compiles CRM activity, drafts and queues a personalized email, then dispatches queued mail. The graph also preserves the distinct campaign-planning and template-authoring branches. Some backend links are based on README descriptions and module boundaries; unsampled implementation details are not expanded.

Main entry points: [`finbyzreach/tasks/every_4PM/smart_followup.py`](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py) (Stale Follow-up Job), [`finbyzreach/email_template_builder/api.py`](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/api.py) (Template Builder API), [`finbyzreach/utils/research.py`](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/utils/research.py) (Prospect Research), [`finbyzreach/tasks/every_10_min/enqueue_outbound_emails.py`](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_10_min/enqueue_outbound_emails.py) (Outbound Dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_followup["Smart Follow-ups"]
  node_followup_job["Stale Follow-up Job<br/>[smart_followup.py]"]
  node_research["Prospect Research<br/>[research.py]"]
  node_agent_service["AI Agent Service"]
  node_activity_context["CRM Activity Context<br/>[smart_followup.py]"]
  node_email_agent["Email Drafting Agent<br/>[smart_followup.py]"]
  node_communication["Draft Communication"]
  node_outbound_job["Outbound Dispatcher"]
  node_mail_queue["Frappe Email Queue"]
end

subgraph group_campaign["Email Campaigns"]
  node_campaign_studio["Campaign Studio"]
  node_campaign_rules["Campaign Planning<br/>[email_marketing.py]"]
  node_audience["Audience Selection<br/>[email_marketing.py]"]
  node_campaign_store[("Campaign Records<br/>[email_marketing.py]")]
  node_campaign_sender["Campaign Dispatcher<br/>[email_marketing.py]"]
end

subgraph group_template["Template Builder"]
  node_builder_ui["Visual Builder<br/>[App.tsx]"]
  node_builder_controller["Builder Controller"]
  node_builder_api["Template Builder API<br/>[api.py]"]
  node_compiler["Email Compiler<br/>[compiler.py]"]
  node_template_services["Template Services<br/>[services.py]"]
  node_template_records[("Email Templates")]
  node_revision_records[("Builder Revisions")]
end

subgraph group_crm["CRM Data"]
  node_crm_records[("CRM Records")]
  node_crm_hooks["CRM Record Hooks<br/>[lead.py]"]
  node_research_api["Research API<br/>[lead.py]"]
end

node_scheduler(("Frappe Scheduler"))
node_studio_user(("Campaign Manager"))
node_template_user(("Template Author"))

node_scheduler -->|"triggers daily"| node_followup_job
node_followup_job -->|"checks opportunities"| node_crm_records
node_followup_job -->|"requests research"| node_research
node_research -->|"reads and enriches"| node_crm_records
node_research -->|"invokes"| node_agent_service
node_followup_job -->|"gathers history"| node_activity_context
node_followup_job -->|"requests draft"| node_email_agent
node_email_agent -->|"invokes"| node_agent_service
node_followup_job -->|"creates draft"| node_communication
node_communication -->|"saves communication"| node_crm_records
node_scheduler -->|"triggers every 10m"| node_outbound_job
node_outbound_job -->|"loads queued mail"| node_communication
node_outbound_job -->|"dispatches"| node_mail_queue
node_crm_hooks -.->|"requests enrichment"| node_research
node_research_api -->|"calls"| node_research
node_studio_user -->|"plans campaign"| node_campaign_studio
node_campaign_studio -->|"configures broadcast"| node_campaign_rules
node_campaign_rules -->|"selects recipients"| node_audience
node_campaign_rules -->|"saves campaign"| node_campaign_store
node_audience -->|"records recipients"| node_campaign_store
node_scheduler -->|"triggers delivery"| node_campaign_sender
node_campaign_sender -->|"loads due recipients"| node_campaign_store
node_campaign_sender -->|"queues campaign mail"| node_mail_queue
node_template_user -->|"edits template"| node_builder_ui
node_builder_ui -->|"delegates editing"| node_builder_controller
node_builder_controller -->|"requests template actions"| node_builder_api
node_builder_api -->|"compiles content"| node_compiler
node_builder_api -->|"loads and renders"| node_template_services
node_template_services -->|"reads template"| node_template_records
node_builder_api -->|"saves template"| node_template_records
node_builder_api -->|"stores revisions"| node_revision_records
node_template_services -->|"renders lead context"| node_crm_records

click node_followup_job "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py"
click node_research "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/utils/research.py"
click node_activity_context "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py"
click node_email_agent "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py"
click node_communication "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/ai_email_outreach/doctype/communication_email/communication_email.py"
click node_outbound_job "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_10_min/enqueue_outbound_emails.py"
click node_crm_hooks "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/doc_events/lead.py"
click node_research_api "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/api/lead.py"
click node_campaign_studio "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/finbyzreach/page/email_campaign_studio/email_campaign_studio.py"
click node_campaign_rules "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py"
click node_audience "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py"
click node_campaign_store "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py"
click node_campaign_sender "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py"
click node_builder_ui "https://github.com/finbyz/finbyzreach/blob/main/builder/src/App.tsx"
click node_builder_controller "https://github.com/finbyz/finbyzreach/blob/main/builder/src/hooks/useEmailBuilderController.ts"
click node_builder_api "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/api.py"
click node_compiler "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/compiler.py"
click node_template_services "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/services.py"
click node_revision_records "https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/doctype/email_builder_revision/email_builder_revision.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_followup_job,node_research,node_agent_service,node_activity_context,node_email_agent,node_communication,node_outbound_job,node_mail_queue toneBlue
class node_campaign_studio,node_campaign_rules,node_audience,node_campaign_store,node_campaign_sender toneAmber
class node_builder_ui,node_builder_controller,node_builder_api,node_compiler,node_template_services,node_template_records,node_revision_records toneMint
class node_crm_records,node_crm_hooks,node_research_api,node_scheduler toneRose
class node_studio_user,node_template_user toneIndigo
```

## Components

### Smart Follow-ups

- [Stale Follow-up Job](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py): `finbyzreach/tasks/every_4PM/smart_followup.py`
- [Prospect Research](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/utils/research.py): `finbyzreach/utils/research.py`
- **AI Agent Service**
- [CRM Activity Context](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py): `finbyzreach/tasks/every_4PM/smart_followup.py`
- [Email Drafting Agent](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_4PM/smart_followup.py): `finbyzreach/tasks/every_4PM/smart_followup.py`
- [Draft Communication](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/ai_email_outreach/doctype/communication_email/communication_email.py): `finbyzreach/ai_email_outreach/doctype/communication_email/communication_email.py`
- [Outbound Dispatcher](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/tasks/every_10_min/enqueue_outbound_emails.py): `finbyzreach/tasks/every_10_min/enqueue_outbound_emails.py`
- **Frappe Email Queue**

### Email Campaigns

- [Campaign Studio](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/finbyzreach/page/email_campaign_studio/email_campaign_studio.py): `finbyzreach/finbyzreach/page/email_campaign_studio/email_campaign_studio.py`
- [Campaign Planning](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py): `finbyzreach/email_marketing.py`
- [Audience Selection](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py): `finbyzreach/email_marketing.py`
- [Campaign Records](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py): `finbyzreach/email_marketing.py`
- [Campaign Dispatcher](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_marketing.py): `finbyzreach/email_marketing.py`

### Template Builder

- [Visual Builder](https://github.com/finbyz/finbyzreach/blob/main/builder/src/App.tsx): `builder/src/App.tsx`
- [Builder Controller](https://github.com/finbyz/finbyzreach/blob/main/builder/src/hooks/useEmailBuilderController.ts): `builder/src/hooks/useEmailBuilderController.ts`
- [Template Builder API](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/api.py): `finbyzreach/email_template_builder/api.py`
- [Email Compiler](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/compiler.py): `finbyzreach/email_template_builder/compiler.py`
- [Template Services](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/services.py): `finbyzreach/email_template_builder/services.py`
- **Email Templates**
- [Builder Revisions](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/email_template_builder/doctype/email_builder_revision/email_builder_revision.py): `finbyzreach/email_template_builder/doctype/email_builder_revision/email_builder_revision.py`

### CRM Data

- **CRM Records**
- [CRM Record Hooks](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/doc_events/lead.py): `finbyzreach/doc_events/lead.py`
- [Research API](https://github.com/finbyz/finbyzreach/blob/main/finbyzreach/api/lead.py): `finbyzreach/api/lead.py`

### Other components

- **Frappe Scheduler**
- **Campaign Manager**
- **Template Author**

## Connections

- Frappe Scheduler → Stale Follow-up Job: triggers daily
- Stale Follow-up Job → CRM Records: checks opportunities
- Stale Follow-up Job → Prospect Research: requests research
- Prospect Research → CRM Records: reads and enriches
- Prospect Research → AI Agent Service: invokes
- Stale Follow-up Job → CRM Activity Context: gathers history
- Stale Follow-up Job → Email Drafting Agent: requests draft
- Email Drafting Agent → AI Agent Service: invokes
- Stale Follow-up Job → Draft Communication: creates draft
- Draft Communication → CRM Records: saves communication
- Frappe Scheduler → Outbound Dispatcher: triggers every 10m
- Outbound Dispatcher → Draft Communication: loads queued mail
- Outbound Dispatcher → Frappe Email Queue: dispatches
- CRM Record Hooks → Prospect Research: requests enrichment
- Research API → Prospect Research: calls
- Campaign Manager → Campaign Studio: plans campaign
- Campaign Studio → Campaign Planning: configures broadcast
- Campaign Planning → Audience Selection: selects recipients
- Campaign Planning → Campaign Records: saves campaign
- Audience Selection → Campaign Records: records recipients
- Frappe Scheduler → Campaign Dispatcher: triggers delivery
- Campaign Dispatcher → Campaign Records: loads due recipients
- Campaign Dispatcher → Frappe Email Queue: queues campaign mail
- Template Author → Visual Builder: edits template
- Visual Builder → Builder Controller: delegates editing
- Builder Controller → Template Builder API: requests template actions
- Template Builder API → Email Compiler: compiles content
- Template Builder API → Template Services: loads and renders
- Template Services → Email Templates: reads template
- Template Builder API → Email Templates: saves template
- Template Builder API → Builder Revisions: stores revisions
- Template Services → CRM Records: renders lead context