# flighttosalesforce/batch-framework architecture

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

- Interactive diagram: https://gitdiagram.com/flighttosalesforce/batch-framework
- Repository: https://github.com/flighttosalesforce/batch-framework

## Overview

The repository’s primary product is a Salesforce Apex batch framework: administrators configure scheduled jobs, the hourly scheduler queues due work, and an orchestrator runs jobs serially while recording outcomes. A separate metadata-health agent collects Salesforce metadata, checks it deterministically and with AI, and emits reports and optional pull-request feedback. The README documents the batch lifecycle; agent relationships below are limited to the shown entry-point calls and imports. UI automation and delivery tooling are excluded.

Main entry points: [`metadata-agent/src/index.mjs`](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/index.mjs) (Agent entry point), [`force-app/main/default/classes/BatchQueueService.cls`](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchQueueService.cls) (Queue service), [`force-app/main/default/classes/BatchOrchestrator.cls`](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchOrchestrator.cls) (Job orchestrator), [`force-app/main/default/classes/BatchFrameworkScheduler.cls`](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchFrameworkScheduler.cls) (Hourly scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_batch["Batch execution"]
  node_scheduler["Hourly scheduler"]
  node_sync["Schedule sync"]
  node_queue_service["Queue service"]
  node_orchestrator["Job orchestrator"]
  node_job_contract["Job contract<br/>[IBatchJob.cls]"]
  node_base_batch["Batch base class<br/>[BaseBatch.cls]"]
  node_custom_job["Custom batch job"]
end

subgraph group_config["Schedules and tracking"]
  node_framework_records[("Job schedules")]
  node_handler_metadata[("Deployable schedules")]
  node_queue_records[("Run records")]
  node_failure_records[("Failure records")]
end

subgraph group_agent["Metadata health agent"]
  node_agent_entry["Agent entry point<br/>[index.mjs]"]
  node_collection["Metadata collection<br/>[collect.mjs]"]
  node_static_checks["Static checks<br/>[static-checks.mjs]"]
  node_ai_review["AI review<br/>[analyze.mjs]"]
  node_sf_integration["Salesforce integration<br/>[salesforce.mjs]"]
  node_reporting["Report generation<br/>[report.mjs]"]
  node_pr_feedback["PR feedback<br/>[github.mjs]"]
end

subgraph group_integrations["External services"]
  node_salesforce_org[("Salesforce org")]
  node_anthropic["Anthropic / Claude"]
  node_github["GitHub"]
  node_report_files["Report files"]
end

node_admin(("Org administrator"))

node_admin -->|"schedules"| node_scheduler
node_scheduler -->|"syncs schedules"| node_sync
node_scheduler -->|"queues due jobs"| node_queue_service
node_sync -->|"reads schedules"| node_handler_metadata
node_sync -->|"copies schedules"| node_framework_records
node_queue_service -->|"selects due jobs"| node_framework_records
node_queue_service -->|"creates run records"| node_queue_records
node_queue_service -->|"advances next run"| node_framework_records
node_queue_service -->|"starts chain"| node_orchestrator
node_orchestrator -->|"selects oldest queued"| node_queue_records
node_orchestrator -->|"dispatches job"| node_job_contract
node_custom_job -.->|"extends"| node_base_batch
node_base_batch -->|"records outcome"| node_queue_service
node_base_batch -->|"starts next job"| node_orchestrator
node_agent_entry -->|"collects files"| node_collection
node_agent_entry -->|"runs checks"| node_static_checks
node_agent_entry -->|"requests review"| node_ai_review
node_agent_entry -->|"retrieves org data"| node_sf_integration
node_agent_entry -->|"writes report"| node_reporting
node_agent_entry -->|"posts PR feedback"| node_pr_feedback
node_ai_review -->|"uses check IDs"| node_static_checks
node_sf_integration -->|"retrieves metadata"| node_salesforce_org
node_ai_review -.->|"requests analysis"| node_anthropic
node_pr_feedback -->|"posts comments"| node_github
node_reporting -->|"writes reports"| node_report_files

click node_scheduler "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchFrameworkScheduler.cls"
click node_sync "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchHandlerSyncService.cls"
click node_queue_service "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchQueueService.cls"
click node_orchestrator "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchOrchestrator.cls"
click node_job_contract "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/IBatchJob.cls"
click node_base_batch "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BaseBatch.cls"
click node_custom_job "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchFrameworkSmokeJob.cls"
click node_framework_records "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchFramework__c/BatchFramework__c.object-meta.xml"
click node_handler_metadata "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchHandler__mdt/BatchHandler__mdt.object-meta.xml"
click node_queue_records "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchQueue__c/BatchQueue__c.object-meta.xml"
click node_failure_records "https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchFailure__c/BatchFailure__c.object-meta.xml"
click node_agent_entry "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/index.mjs"
click node_collection "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/collect.mjs"
click node_static_checks "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/static-checks.mjs"
click node_ai_review "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/analyze.mjs"
click node_sf_integration "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/salesforce.mjs"
click node_reporting "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/report.mjs"
click node_pr_feedback "https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/github.mjs"

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_scheduler,node_sync,node_queue_service,node_orchestrator,node_job_contract,node_base_batch,node_custom_job toneBlue
class node_framework_records,node_handler_metadata,node_queue_records,node_failure_records toneAmber
class node_agent_entry,node_collection,node_static_checks,node_ai_review,node_sf_integration,node_reporting,node_pr_feedback toneMint
class node_salesforce_org,node_anthropic,node_github,node_report_files toneRose
class node_admin toneIndigo
```

## Components

### Batch execution

- [Hourly scheduler](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchFrameworkScheduler.cls): `force-app/main/default/classes/BatchFrameworkScheduler.cls`
- [Schedule sync](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchHandlerSyncService.cls): `force-app/main/default/classes/BatchHandlerSyncService.cls`
- [Queue service](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchQueueService.cls): `force-app/main/default/classes/BatchQueueService.cls`
- [Job orchestrator](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchOrchestrator.cls): `force-app/main/default/classes/BatchOrchestrator.cls`
- [Job contract](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/IBatchJob.cls): `force-app/main/default/classes/IBatchJob.cls`
- [Batch base class](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BaseBatch.cls): `force-app/main/default/classes/BaseBatch.cls`
- [Custom batch job](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/classes/BatchFrameworkSmokeJob.cls): `force-app/main/default/classes/BatchFrameworkSmokeJob.cls`

### Schedules and tracking

- [Job schedules](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchFramework__c/BatchFramework__c.object-meta.xml): `force-app/main/default/objects/BatchFramework__c/BatchFramework__c.object-meta.xml`
- [Deployable schedules](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchHandler__mdt/BatchHandler__mdt.object-meta.xml): `force-app/main/default/objects/BatchHandler__mdt/BatchHandler__mdt.object-meta.xml`
- [Run records](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchQueue__c/BatchQueue__c.object-meta.xml): `force-app/main/default/objects/BatchQueue__c/BatchQueue__c.object-meta.xml`
- [Failure records](https://github.com/flighttosalesforce/batch-framework/blob/dev/force-app/main/default/objects/BatchFailure__c/BatchFailure__c.object-meta.xml): `force-app/main/default/objects/BatchFailure__c/BatchFailure__c.object-meta.xml`

### Metadata health agent

- [Agent entry point](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/index.mjs): `metadata-agent/src/index.mjs`
- [Metadata collection](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/collect.mjs): `metadata-agent/src/collect.mjs`
- [Static checks](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/static-checks.mjs): `metadata-agent/src/static-checks.mjs`
- [AI review](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/analyze.mjs): `metadata-agent/src/analyze.mjs`
- [Salesforce integration](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/salesforce.mjs): `metadata-agent/src/salesforce.mjs`
- [Report generation](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/report.mjs): `metadata-agent/src/report.mjs`
- [PR feedback](https://github.com/flighttosalesforce/batch-framework/blob/dev/metadata-agent/src/github.mjs): `metadata-agent/src/github.mjs`

### External services

- **Salesforce org**
- **Anthropic / Claude**
- **GitHub**
- **Report files**

### Other components

- **Org administrator**

## Connections

- Org administrator → Hourly scheduler: schedules (evidence: `README.md`)
- Hourly scheduler → Schedule sync: syncs schedules (evidence: `README.md`)
- Hourly scheduler → Queue service: queues due jobs (evidence: `README.md`)
- Schedule sync → Deployable schedules: reads schedules (evidence: `README.md`)
- Schedule sync → Job schedules: copies schedules (evidence: `README.md`)
- Queue service → Job schedules: selects due jobs (evidence: `README.md`)
- Queue service → Run records: creates run records (evidence: `README.md`)
- Queue service → Job schedules: advances next run (evidence: `README.md`)
- Queue service → Job orchestrator: starts chain (evidence: `README.md`)
- Job orchestrator → Run records: selects oldest queued (evidence: `README.md`)
- Job orchestrator → Job contract: dispatches job (evidence: `README.md`)
- Custom batch job → Batch base class: extends
- Batch base class → Queue service: records outcome (evidence: `README.md`)
- Batch base class → Job orchestrator: starts next job (evidence: `README.md`)
- Agent entry point → Metadata collection: collects files (evidence: `metadata-agent/src/index.mjs`)
- Agent entry point → Static checks: runs checks (evidence: `metadata-agent/src/index.mjs`)
- Agent entry point → AI review: requests review (evidence: `metadata-agent/src/index.mjs`)
- Agent entry point → Salesforce integration: retrieves org data (evidence: `metadata-agent/src/index.mjs`)
- Agent entry point → Report generation: writes report (evidence: `metadata-agent/src/index.mjs`)
- Agent entry point → PR feedback: posts PR feedback (evidence: `metadata-agent/src/index.mjs`)
- AI review → Static checks: uses check IDs (evidence: `metadata-agent/src/analyze.mjs`)
- Salesforce integration → Salesforce org: retrieves metadata (evidence: `metadata-agent/src/salesforce.mjs`)
- AI review → Anthropic / Claude: requests analysis
- PR feedback → GitHub: posts comments (evidence: `metadata-agent/src/github.mjs`)
- Report generation → Report files: writes reports (evidence: `metadata-agent/src/report.mjs`)