# mrwhitehat-coder/instagram-dm-automation-free architecture

> Architecture diagram of the GitHub repository mrwhitehat-coder/instagram-dm-automation-free, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrwhitehat-coder/instagram-dm-automation-free
- Repository: https://github.com/mrwhitehat-coder/instagram-dm-automation-free

## Overview

AutoDM is a self-hosted Instagram comment-to-DM automation running on a Cloudflare Worker. A commenter triggers a verified webhook; the worker dispatches events to automation logic, which matches rules, sends private/public replies, handles button taps and optional follow checks, then delivers the configured link. The dashboard configures automations and presents activity, analytics, setup, and approval guidance. D1 stores rules, settings, pending conversations, and activity. Edges reflect shown calls or README-documented behavior; dashboard/API wiring and some routing details are not fully visible in the excerpts, so those links are marked unverified.

Main entry points: [`src/api.ts`](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/api.ts) (Admin API), [`src/index.ts`](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/index.ts) (Worker entry), [`src/flow.ts`](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/flow.ts) (Webhook automation), [`src/instagram.ts`](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/instagram.ts) (Instagram client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard and setup"]
  node_dashboard["Dashboard<br/>[app.js]"]
  node_privacy["Privacy policy<br/>[privacy.ts]"]
end

subgraph group_worker["Worker and API"]
  node_worker["Worker entry<br/>[index.ts]"]
  node_adminapi["Admin API<br/>[api.ts]"]
end

subgraph group_automation["Automation workflow"]
  node_automation["Webhook automation<br/>[flow.ts]"]
  node_rules["Rule matching<br/>[rules.ts]"]
end

subgraph group_integrations["Security and integrations"]
  node_auth["Dashboard auth<br/>[auth.ts]"]
  node_instagram["Instagram client<br/>[instagram.ts]"]
  node_token["Token lifecycle<br/>[token.ts]"]
  node_signature["Signature checks<br/>[signature.ts]"]
end

subgraph group_state["Persistence"]
  node_store["Data access<br/>[store.ts]"]
  node_d1[("Cloudflare D1")]
end

node_creator(("Account owner"))
node_meta["Meta Instagram API"]
node_commenter(("Instagram commenter"))

node_creator -->|"configures"| node_dashboard
node_dashboard -.->|"uses API"| node_adminapi
node_worker -.->|"routes requests"| node_adminapi
node_worker -->|"verifies webhook"| node_signature
node_worker -->|"dispatches events"| node_automation
node_commenter -->|"comments or taps"| node_meta
node_meta -->|"delivers webhook"| node_worker
node_automation -->|"matches rules"| node_rules
node_automation -->|"sends messages"| node_instagram
node_automation -->|"reads and writes"| node_store
node_adminapi -->|"checks sessions"| node_auth
node_adminapi -->|"validates rules"| node_rules
node_adminapi -->|"reads and writes"| node_store
node_adminapi -->|"gets or refreshes"| node_token
node_adminapi -->|"creates client"| node_instagram
node_auth -->|"uses HMAC"| node_signature
node_token -->|"refreshes token"| node_instagram
node_token -->|"persists token"| node_store
node_store -->|"queries"| node_d1
node_instagram -->|"calls API"| node_meta
node_worker -->|"serves policy"| node_privacy

click node_dashboard "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/public/app.js"
click node_worker "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/index.ts"
click node_adminapi "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/api.ts"
click node_auth "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/auth.ts"
click node_automation "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/flow.ts"
click node_rules "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/rules.ts"
click node_instagram "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/instagram.ts"
click node_token "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/token.ts"
click node_signature "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/signature.ts"
click node_privacy "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/privacy.ts"
click node_store "https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/store.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_dashboard,node_privacy toneBlue
class node_worker,node_adminapi toneAmber
class node_automation,node_rules,node_meta toneMint
class node_auth,node_instagram,node_token,node_signature toneRose
class node_store,node_d1,node_creator,node_commenter toneIndigo
```

## Components

### Dashboard and setup

- [Dashboard](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/public/app.js): `public/app.js`
- [Privacy policy](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/privacy.ts): `src/privacy.ts`

### Worker and API

- [Worker entry](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/index.ts): `src/index.ts`
- [Admin API](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/api.ts): `src/api.ts`

### Automation workflow

- [Webhook automation](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/flow.ts): `src/flow.ts`
- [Rule matching](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/rules.ts): `src/rules.ts`

### Security and integrations

- [Dashboard auth](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/auth.ts): `src/auth.ts`
- [Instagram client](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/instagram.ts): `src/instagram.ts`
- [Token lifecycle](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/token.ts): `src/token.ts`
- [Signature checks](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/signature.ts): `src/signature.ts`

### Persistence

- [Data access](https://github.com/mrwhitehat-coder/instagram-dm-automation-free/blob/main/src/store.ts): `src/store.ts`
- **Cloudflare D1**

### Other components

- **Account owner**
- **Meta Instagram API**
- **Instagram commenter**

## Connections

- Account owner → Dashboard: configures (evidence: `README.md`)
- Dashboard → Admin API: uses API
- Worker entry → Admin API: routes requests (evidence: `src/index.ts`)
- Worker entry → Signature checks: verifies webhook (evidence: `src/index.ts`)
- Worker entry → Webhook automation: dispatches events (evidence: `src/index.ts`)
- Instagram commenter → Meta Instagram API: comments or taps (evidence: `README.md`)
- Meta Instagram API → Worker entry: delivers webhook (evidence: `README.md`)
- Webhook automation → Rule matching: matches rules (evidence: `src/flow.ts`)
- Webhook automation → Instagram client: sends messages (evidence: `src/flow.ts`)
- Webhook automation → Data access: reads and writes (evidence: `src/flow.ts`)
- Admin API → Dashboard auth: checks sessions (evidence: `src/api.ts`)
- Admin API → Rule matching: validates rules (evidence: `src/api.ts`)
- Admin API → Data access: reads and writes (evidence: `src/api.ts`)
- Admin API → Token lifecycle: gets or refreshes (evidence: `src/api.ts`)
- Admin API → Instagram client: creates client (evidence: `src/api.ts`)
- Dashboard auth → Signature checks: uses HMAC (evidence: `src/auth.ts`)
- Token lifecycle → Instagram client: refreshes token (evidence: `src/token.ts`)
- Token lifecycle → Data access: persists token (evidence: `src/token.ts`)
- Data access → Cloudflare D1: queries (evidence: `src/store.ts`)
- Instagram client → Meta Instagram API: calls API (evidence: `README.md`)
- Worker entry → Privacy policy: serves policy (evidence: `src/index.ts`)
