# phuuthanh-dev/meta-marketing-dashboard architecture

> Architecture diagram of the GitHub repository phuuthanh-dev/meta-marketing-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phuuthanh-dev/meta-marketing-dashboard
- Repository: https://github.com/phuuthanh-dev/meta-marketing-dashboard

## Overview

Meta Marketing Dashboard combines Facebook organic, Ads, Instagram reporting, CSV export, live updates, and content planning. Users view reporting through the dashboard; the server exposes authenticated API routes backed by SQLite, while fetchers collect platform data. Content planning adds Google Sheets/Drive synchronization and publishing workflows. Scheduled collection is optional. The README documents the product capabilities; some route wiring and frontend behavior are unsampled, so those relationships are shown only where supported or marked unverified.

Main entry points: [`src/server.js`](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/server.js) (HTTP Server), [`public/js/api.js`](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/api.js) (API Client), [`src/database.js`](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/database.js) (SQLite Store), [`src/content-plan/index.js`](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/index.js) (Content Plan API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard UI"]
  node_web_ui["Dashboard Shell<br/>[app.js]"]
  node_api_client["API Client<br/>[api.js]"]
  node_charts["Analytics Charts<br/>[charts.js]"]
  node_additional_charts["Extended Charts"]
  node_ads_ui["Ads Dashboard<br/>[ads.js]"]
  node_instagram_ui["Instagram Dashboard<br/>[instagram.js]"]
  node_phase1_ui["Page Insights<br/>[phase1.js]"]
  node_phase2_ui["Engagement Views<br/>[phase2.js]"]
  node_phase3_ui["Management Views<br/>[phase3.js]"]
  node_phase3_charts["Management Charts<br/>[phase3-charts.js]"]
  node_content_ui["Content Plan UI<br/>[content-plan.js]"]
end

subgraph group_api["Application API"]
  node_server["HTTP Server<br/>[server.js]"]
  node_database[("SQLite Store<br/>[database.js]")]
  node_config["Runtime Config<br/>[config.js]"]
end

subgraph group_collection["Data Collection"]
  node_facebook_api["Facebook API<br/>[api.js]"]
  node_facebook_metrics["Facebook Metrics<br/>[metrics.js]"]
  node_ads_api["Meta Ads API<br/>[api.js]"]
  node_ads_fetcher["Ads Collector<br/>[fetcher.js]"]
  node_instagram_api["Instagram API<br/>[api.js]"]
  node_instagram_fetcher["Instagram Collector<br/>[fetcher.js]"]
  node_scheduler["Scheduler<br/>[scheduler.js]"]
end

subgraph group_planning["Content Planning"]
  node_content_router["Content Plan API<br/>[index.js]"]
  node_sheets_sync["Sheets Sync<br/>[sheets-sync.js]"]
  node_sheet_updater["Sheet Updater<br/>[sheet-updater.js]"]
  node_drive_download["Drive Media<br/>[drive-download.js]"]
  node_cloudinary["Media Hosting<br/>[cloudinary.js]"]
end

node_marketer(("Marketer"))
node_browser(("Browser"))
node_meta{{"Meta Graph API"}}
node_google_sheets{{"Google Sheets"}}
node_google_drive{{"Google Drive"}}
node_cloudinary_service{{"Cloudinary"}}

node_marketer -->|"uses"| node_browser
node_browser -.->|"loads dashboard"| node_web_ui
node_web_ui -.->|"uses"| node_api_client
node_api_client -.->|"requests API"| node_server
node_server -->|"reads and writes"| node_database
node_server -.->|"routes platform actions"| node_facebook_api
node_server -.->|"routes platform actions"| node_ads_api
node_server -.->|"routes platform actions"| node_instagram_api
node_server -->|"mounts routes"| node_content_router
node_server -->|"uses settings"| node_config
node_facebook_metrics -->|"fetches metrics"| node_facebook_api
node_facebook_metrics -->|"saves metrics"| node_database
node_ads_fetcher -->|"fetches insights"| node_ads_api
node_ads_fetcher -->|"saves insights"| node_database
node_instagram_fetcher -->|"fetches insights"| node_instagram_api
node_instagram_fetcher -->|"saves insights"| node_database
node_facebook_api -->|"calls Graph API"| node_meta
node_ads_api -->|"calls Graph API"| node_meta
node_instagram_api -->|"calls Graph API"| node_meta
node_scheduler -->|"runs collection"| node_facebook_metrics
node_scheduler -->|"runs collection"| node_ads_fetcher
node_scheduler -->|"runs collection"| node_instagram_fetcher
node_scheduler -->|"runs sync"| node_sheets_sync
node_scheduler -->|"processes publish jobs"| node_database
node_content_router -->|"reads and writes plans"| node_database
node_content_router -->|"triggers sync"| node_sheets_sync
node_content_router -->|"streams media"| node_drive_download
node_content_router -->|"updates sheet"| node_sheet_updater
node_sheets_sync -->|"reads sheet"| node_google_sheets
node_sheets_sync -.->|"stores plan"| node_database
node_drive_download -->|"downloads media"| node_google_drive
node_drive_download -->|"uploads media"| node_cloudinary
node_cloudinary -.->|"hosts media"| node_cloudinary_service
node_content_ui -.->|"uses plan API"| node_content_router
node_ads_ui -.->|"requests reporting"| node_api_client
node_instagram_ui -.->|"requests reporting"| node_api_client
node_phase1_ui -.->|"requests reporting"| node_api_client
node_phase2_ui -.->|"requests reporting"| node_api_client
node_phase3_ui -.->|"requests management"| node_api_client
node_charts -.->|"renders charts"| node_web_ui
node_additional_charts -.->|"renders charts"| node_web_ui
node_phase3_charts -.->|"renders charts"| node_phase3_ui

click node_web_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/app.js"
click node_api_client "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/api.js"
click node_charts "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/charts.js"
click node_additional_charts "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/additional-charts.js"
click node_ads_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/ads.js"
click node_instagram_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/instagram.js"
click node_phase1_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase1.js"
click node_phase2_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase2.js"
click node_phase3_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase3.js"
click node_phase3_charts "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase3-charts.js"
click node_content_ui "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/content-plan.js"
click node_server "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/server.js"
click node_database "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/database.js"
click node_config "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/config.js"
click node_facebook_api "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/facebook/api.js"
click node_facebook_metrics "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/facebook/metrics.js"
click node_ads_api "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/meta-ads/api.js"
click node_ads_fetcher "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/meta-ads/fetcher.js"
click node_instagram_api "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/instagram/api.js"
click node_instagram_fetcher "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/instagram/fetcher.js"
click node_scheduler "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/scheduler.js"
click node_content_router "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/index.js"
click node_sheets_sync "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/sheets-sync.js"
click node_sheet_updater "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/sheet-updater.js"
click node_drive_download "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/drive-download.js"
click node_cloudinary "https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/cloudinary.js"

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_web_ui,node_api_client,node_charts,node_additional_charts,node_ads_ui,node_instagram_ui,node_phase1_ui,node_phase2_ui,node_phase3_ui,node_phase3_charts,node_content_ui,node_browser toneBlue
class node_server,node_database,node_config toneAmber
class node_facebook_api,node_facebook_metrics,node_ads_api,node_ads_fetcher,node_instagram_api,node_instagram_fetcher,node_scheduler,node_meta toneMint
class node_content_router,node_sheets_sync,node_sheet_updater,node_drive_download,node_cloudinary toneRose
class node_marketer,node_google_sheets,node_google_drive,node_cloudinary_service toneIndigo
```

## Components

### Dashboard UI

- [Dashboard Shell](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/app.js): `public/js/app.js`
- [API Client](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/api.js): `public/js/api.js`
- [Analytics Charts](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/charts.js): `public/js/charts.js`
- [Extended Charts](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/additional-charts.js): `public/js/additional-charts.js`
- [Ads Dashboard](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/ads.js): `public/js/ads.js`
- [Instagram Dashboard](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/instagram.js): `public/js/instagram.js`
- [Page Insights](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase1.js): `public/js/phase1.js`
- [Engagement Views](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase2.js): `public/js/phase2.js`
- [Management Views](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase3.js): `public/js/phase3.js`
- [Management Charts](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/phase3-charts.js): `public/js/phase3-charts.js`
- [Content Plan UI](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/public/js/content-plan.js): `public/js/content-plan.js`

### Application API

- [HTTP Server](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/server.js): `src/server.js`
- [SQLite Store](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/database.js): `src/database.js`
- [Runtime Config](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/config.js): `src/config.js`

### Data Collection

- [Facebook API](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/facebook/api.js): `src/facebook/api.js`
- [Facebook Metrics](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/facebook/metrics.js): `src/facebook/metrics.js`
- [Meta Ads API](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/meta-ads/api.js): `src/meta-ads/api.js`
- [Ads Collector](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/meta-ads/fetcher.js): `src/meta-ads/fetcher.js`
- [Instagram API](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/instagram/api.js): `src/instagram/api.js`
- [Instagram Collector](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/instagram/fetcher.js): `src/instagram/fetcher.js`
- [Scheduler](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/scheduler.js): `src/scheduler.js`

### Content Planning

- [Content Plan API](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/index.js): `src/content-plan/index.js`
- [Sheets Sync](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/sheets-sync.js): `src/content-plan/sheets-sync.js`
- [Sheet Updater](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/sheet-updater.js): `src/content-plan/sheet-updater.js`
- [Drive Media](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/content-plan/drive-download.js): `src/content-plan/drive-download.js`
- [Media Hosting](https://github.com/phuuthanh-dev/meta-marketing-dashboard/blob/main/src/cloudinary.js): `src/cloudinary.js`

### Other components

- **Marketer**
- **Browser**
- **Meta Graph API**
- **Google Sheets**
- **Google Drive**
- **Cloudinary**

## Connections

- Marketer → Browser: uses (evidence: `README.md`)
- Browser → Dashboard Shell: loads dashboard
- Dashboard Shell → API Client: uses
- API Client → HTTP Server: requests API
- HTTP Server → SQLite Store: reads and writes (evidence: `src/server.js`)
- HTTP Server → Facebook API: routes platform actions (evidence: `src/server.js`)
- HTTP Server → Meta Ads API: routes platform actions (evidence: `src/server.js`)
- HTTP Server → Instagram API: routes platform actions (evidence: `src/server.js`)
- HTTP Server → Content Plan API: mounts routes (evidence: `src/server.js`)
- HTTP Server → Runtime Config: uses settings (evidence: `src/server.js`)
- Facebook Metrics → Facebook API: fetches metrics (evidence: `src/facebook/metrics.js`)
- Facebook Metrics → SQLite Store: saves metrics (evidence: `src/facebook/metrics.js`)
- Ads Collector → Meta Ads API: fetches insights (evidence: `src/meta-ads/fetcher.js`)
- Ads Collector → SQLite Store: saves insights (evidence: `src/meta-ads/fetcher.js`)
- Instagram Collector → Instagram API: fetches insights (evidence: `src/instagram/fetcher.js`)
- Instagram Collector → SQLite Store: saves insights (evidence: `src/instagram/fetcher.js`)
- Facebook API → Meta Graph API: calls Graph API (evidence: `src/facebook/api.js`)
- Meta Ads API → Meta Graph API: calls Graph API (evidence: `src/meta-ads/api.js`)
- Instagram API → Meta Graph API: calls Graph API (evidence: `src/instagram/api.js`)
- Scheduler → Facebook Metrics: runs collection (evidence: `src/scheduler.js`)
- Scheduler → Ads Collector: runs collection (evidence: `src/scheduler.js`)
- Scheduler → Instagram Collector: runs collection (evidence: `src/scheduler.js`)
- Scheduler → Sheets Sync: runs sync (evidence: `src/scheduler.js`)
- Scheduler → SQLite Store: processes publish jobs (evidence: `src/scheduler.js`)
- Content Plan API → SQLite Store: reads and writes plans (evidence: `src/content-plan/index.js`)
- Content Plan API → Sheets Sync: triggers sync (evidence: `src/content-plan/index.js`)
- Content Plan API → Drive Media: streams media (evidence: `src/content-plan/index.js`)
- Content Plan API → Sheet Updater: updates sheet (evidence: `src/content-plan/index.js`)
- Sheets Sync → Google Sheets: reads sheet (evidence: `src/content-plan/sheets-sync.js`)
- Sheets Sync → SQLite Store: stores plan (evidence: `src/content-plan/sheets-sync.js`)
- Drive Media → Google Drive: downloads media (evidence: `src/content-plan/drive-download.js`)
- Drive Media → Media Hosting: uploads media (evidence: `src/content-plan/drive-download.js`)
- Media Hosting → Cloudinary: hosts media
- Content Plan UI → Content Plan API: uses plan API
- Ads Dashboard → API Client: requests reporting
- Instagram Dashboard → API Client: requests reporting
- Page Insights → API Client: requests reporting
- Engagement Views → API Client: requests reporting
- Management Views → API Client: requests management
- Analytics Charts → Dashboard Shell: renders charts
- Extended Charts → Dashboard Shell: renders charts
- Management Charts → Management Views: renders charts
