# tigerzplace/fap-facebookautoposter architecture

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

- Interactive diagram: https://gitdiagram.com/tigerzplace/fap-facebookautoposter
- Repository: https://github.com/tigerzplace/fap-facebookautoposter

## Overview

1. This is a Chrome extension, not a standalone web app. The runtime is split across extension pages (`popup.html`, `background.html`, `frame.html`), a content script injected into Facebook pages, and a set of shared “core” modules under `scripts/core`.

2. The central user-facing surface is the dashboard UI. `pages/popup.html` opens the extension experience, and the dashboard logic in `scripts/core/dashboard.js` drives the campaign builder: group selection, post composition, delay settings, image selection, campaign loading/saving, and start/pause/resume controls.

3. Facebook page interaction is handled separately from the UI. `scripts/content.js` and `scripts/core/fb.js` are the automation layer that read and manipulate Facebook’s DOM in the current tab, so posting happens through the browser interface rather than a public Facebook API.

4. The posting workflow is orchestration-heavy. The dashboard sends a campaign to the background/orchestration layer, which sequences posts one group at a time, applies wait times, tracks progress, and coordinates retries, pause/resume, and completion handling.

5. The background subsystem lives under `scripts/background/` and is likely responsible for persistent extension behavior: `background.js` as the long-lived coordinator, plus `fix.js` and `get_host.js` for host/tab handling and reliability fixes. This is where cross-tab control and single-instance protection would live.

6. Image posting is its own pipeline. `scripts/core/imageUpload.js` handles file selection, upload progress, preview state, and re-upload on retry. It is integrated into the campaign flow so the same image can be attached across multiple group posts.

7. Link preview and post composition are managed in the core layer. `scripts/core/api.js`, `scripts/core/functions.js`, and `scripts/core/frame.js` appear to support shared utilities, remote preview fetching, and helper-frame behavior used by the dashboard/posting flow.

8. Campaign state is a first-class concept. The README features map to logic for saved campaigns, saved group lists, multiple post variants, delay presets, smart delay recommendations, and post-run summaries. These are likely persisted locally via extension storage rather than a backend.

9. The extension also has a small external-service boundary. `scripts/core/terms.js` and `scripts/core/api.js` suggest calls to Tigerzplace services for licensing/activation and possibly feature gating or metadata, while `scripts/ads.json` looks like remote/config-driven promotional content.

10. The data flow is: user configures a campaign in the dashboard → campaign state is handed to the background/orchestrator → the orchestrator drives the Facebook automation layer on the active tab → success/failure and direct post URLs are streamed back to the dashboard for logs, counters, and the final summary modal.

11. The static assets and styles are purely presentation concerns. `assets/` contains icons, images, and logos; `styles/` contains the extension UI styling. They do not affect the automation architecture, but they support the dashboard and licensing pages.

12. The documentation under `docs/` is operational rather than runtime logic. It provides tutorials, release notes, and Git/license guidance, which is useful context for understanding intended workflows but not part of the execution path.

Main entry points: [`scripts/core/dashboard.js`](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/dashboard.js) (Dashboard), [`scripts/background/background.js`](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/background.js) (Coordinator), [`scripts/content.js`](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/content.js) (Content Script), [`pages/frame.html`](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/frame.html) (Helper Frame)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Extension UI"]
  node_node_popup["Popup UI<br/>extension page<br/>[popup.html]"]
  node_node_dashboard["Dashboard<br/>campaign UI<br/>[dashboard.js]"]
  node_node_styles["Styles<br/>[main.css]"]
end

subgraph group_group_orch["Orchestration"]
  node_node_background_page["Background Page<br/>extension page<br/>[background.html]"]
  node_node_background["Coordinator<br/>background runtime<br/>[background.js]"]
  node_node_fix["Reliability Fixes<br/>background helper<br/>[fix.js]"]
  node_node_get_host["Host Resolver<br/>background helper<br/>[get_host.js]"]
end

subgraph group_group_fb["Facebook Automation"]
  node_node_content["Content Script<br/>in-page script<br/>[content.js]"]
  node_node_fb["FB Automation<br/>DOM automation<br/>[fb.js]"]
end

subgraph group_group_core["Shared Core"]
  node_node_frame_page["Helper Frame<br/>extension page<br/>[frame.html]"]
  node_node_frame["Frame Logic<br/>helper runtime<br/>[frame.js]"]
  node_node_api["API Layer<br/>service client<br/>[api.js]"]
  node_node_functions["Core Utils<br/>shared helpers<br/>[functions.js]"]
  node_node_upload["Image Upload<br/>upload pipeline<br/>[imageUpload.js]"]
  node_node_terms["Licensing<br/>external service<br/>[terms.js]"]
  node_node_ads["Promos<br/>remote config<br/>[ads.json]"]
end

subgraph group_group_assets["Assets & Docs"]
  node_node_assets[("Media Assets<br/>static assets")]
  node_node_docs["Docs<br/>documentation"]
end

node_node_popup -->|"opens"| node_node_dashboard
node_node_dashboard -->|"campaigns"| node_node_background
node_node_background -->|"dispatches"| node_node_content
node_node_content -->|"uses"| node_node_fb
node_node_background -->|"stabilizes"| node_node_fix
node_node_background -->|"resolves"| node_node_get_host
node_node_dashboard -->|"attaches"| node_node_upload
node_node_dashboard -->|"fetches"| node_node_api
node_node_dashboard -->|"shares"| node_node_functions
node_node_dashboard -->|"checks"| node_node_terms
node_node_dashboard -->|"loads"| node_node_frame_page
node_node_frame_page -->|"runs"| node_node_frame
node_node_background -.->|"coordinates"| node_node_frame
node_node_upload -->|"posts media"| node_node_fb
node_node_api -.->|"configures"| node_node_ads
node_node_dashboard -.->|"renders"| node_node_assets
node_node_dashboard -.->|"documents"| node_node_docs
node_node_background_page -->|"hosts"| node_node_background

click node_node_popup "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/popup.html"
click node_node_dashboard "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/dashboard.js"
click node_node_styles "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/styles/main.css"
click node_node_background_page "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/background.html"
click node_node_background "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/background.js"
click node_node_fix "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/fix.js"
click node_node_get_host "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/get_host.js"
click node_node_content "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/content.js"
click node_node_fb "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/fb.js"
click node_node_frame_page "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/frame.html"
click node_node_frame "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/frame.js"
click node_node_api "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/api.js"
click node_node_functions "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/functions.js"
click node_node_upload "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/imageUpload.js"
click node_node_terms "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/terms.js"
click node_node_ads "https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/ads.json"
click node_node_assets "https://github.com/tigerzplace/fap-facebookautoposter/tree/main/assets"
click node_node_docs "https://github.com/tigerzplace/fap-facebookautoposter/tree/main/docs"

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_node_popup,node_node_dashboard,node_node_styles toneBlue
class node_node_background_page,node_node_background,node_node_fix,node_node_get_host toneAmber
class node_node_content,node_node_fb toneMint
class node_node_frame_page,node_node_frame,node_node_api,node_node_functions,node_node_upload,node_node_terms,node_node_ads toneRose
class node_node_assets,node_node_docs toneIndigo
```

## Components

### Extension UI

User-facing extension pages and presentation assets.

- [Popup UI](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/popup.html): extension page · Entry point for the extension experience. · `pages/popup.html`
- [Dashboard](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/dashboard.js): campaign UI · Campaign builder and control surface for selecting groups, composing posts, setting delays, and managing start/pause/resume. · `scripts/core/dashboard.js`
- [Styles](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/styles/main.css): ui styles · Presentation styles for the extension pages. · `styles/main.css`

### Orchestration

Long-lived background coordination and campaign execution.

- [Background Page](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/background.html): extension page · Hidden extension page hosting persistent background behavior. · `pages/background.html`
- [Coordinator](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/background.js): background runtime · Long-lived campaign orchestrator that sequences posts and manages persistence, retries, and completion. · `scripts/background/background.js`
- [Reliability Fixes](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/fix.js): background helper · Host and tab handling fixes for stable extension behavior. · `scripts/background/fix.js`
- [Host Resolver](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/background/get_host.js): background helper · Resolves target host/tab context for cross-tab control. · `scripts/background/get_host.js`

### Facebook Automation

Content-side DOM interaction and posting automation in Facebook tabs.

- [Content Script](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/content.js): in-page script · Injected script that bridges the extension with Facebook pages. · `scripts/content.js`
- [FB Automation](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/fb.js): DOM automation · Facebook page interaction layer for reading and manipulating the current tab. · `scripts/core/fb.js`

### Shared Core

Reusable logic for campaign state, composition, uploads, and service access.

- [Helper Frame](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/pages/frame.html): extension page · Frame page used as part of the posting or preview workflow. · `pages/frame.html`
- [Frame Logic](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/frame.js): helper runtime · Shared frame behavior used by the dashboard and posting flow. · `scripts/core/frame.js`
- [API Layer](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/api.js): service client · Shared remote/service access used for preview or metadata fetching. · `scripts/core/api.js`
- [Core Utils](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/functions.js): shared helpers · General utility functions supporting the campaign flow. · `scripts/core/functions.js`
- [Image Upload](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/imageUpload.js): upload pipeline · Image selection, progress tracking, preview state, and retry upload handling. · `scripts/core/imageUpload.js`
- [Licensing](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/core/terms.js): external service · Terms, activation, or feature-gating boundary to Tigerzplace services. · `scripts/core/terms.js`
- [Promos](https://github.com/tigerzplace/fap-facebookautoposter/blob/main/scripts/ads.json): remote config · Config-driven promotional content. · `scripts/ads.json`

### Assets & Docs

Static resources and operational documentation.

- [Media Assets](https://github.com/tigerzplace/fap-facebookautoposter/tree/main/assets): static assets · Icons, images, and logos used by the extension. · `assets`
- [Docs](https://github.com/tigerzplace/fap-facebookautoposter/tree/main/docs): documentation · Tutorials, release notes, and usage guidance. · `docs`

## Connections

- Popup UI → Dashboard: opens · Popup launches the dashboard experience.
- Dashboard → Coordinator: campaigns · Sends campaign state to the background orchestrator.
- Coordinator → Content Script: dispatches · Coordinates the content script in the active Facebook tab.
- Content Script → FB Automation: uses · Content script relies on the Facebook DOM automation layer.
- Coordinator → Reliability Fixes: stabilizes · Uses reliability helpers for tab and host handling.
- Coordinator → Host Resolver: resolves · Determines the target host/tab context.
- Dashboard → Image Upload: attaches · Connects image selection and retry state to campaigns.
- Dashboard → API Layer: fetches · Uses shared remote access for previews or metadata.
- Dashboard → Core Utils: shares · Reuses common helpers for campaign composition.
- Dashboard → Licensing: checks · Touches licensing or activation gating.
- Dashboard → Helper Frame: loads · Uses the helper frame page during the workflow.
- Helper Frame → Frame Logic: runs · Frame page hosts the shared frame logic.
- Coordinator → Frame Logic: coordinates · Background coordination may use shared frame behavior.
- Image Upload → FB Automation: posts media · Image pipeline feeds the Facebook posting flow.
- API Layer → Promos: configures · Remote/config-driven content supports the extension experience.
- Dashboard → Media Assets: renders · UI uses static icons and images.
- Dashboard → Docs: documents · Operational docs describe the intended workflow.
- Background Page → Coordinator: hosts · Background page hosts the persistent coordinator.