# alcalino100/dashboard-meta-ads architecture

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

- Interactive diagram: https://gitdiagram.com/alcalino100/dashboard-meta-ads
- Repository: https://github.com/alcalino100/dashboard-meta-ads

## Overview

This is a multi-account Meta Ads management dashboard. Users sign in, enter a dashboard with account and date filters, and view Meta account performance and campaign hierarchy; separate management screens support clients, connections, settings, and users. The runtime divides into UI, Meta data access, and Supabase-backed administration. Several screens and routes are represented from the file tree and SOURCE INDEX rather than inspected source, so their internal links are omitted where evidence is unavailable.

Main entry points: [`components/dashboard/dashboard-shell.tsx`](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/dashboard-shell.tsx) (Dashboard shell), [`lib/supabase/admin.ts`](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/supabase/admin.ts) (Server Supabase client), [`app/page.tsx`](https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/page.tsx) (App entry), [`lib/meta-api.ts`](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/meta-api.ts) (Meta Graph integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard experience"]
  node_page["App entry<br/>[page.tsx]"]
  node_auth_ui["Sign-in screens<br/>[auth-screens.tsx]"]
  node_dashboard["Dashboard shell"]
  node_filters["Account and date filters"]
  node_overview["Performance overview"]
  node_hierarchy["Campaign hierarchy"]
  node_creatives["Creative reporting"]
  node_alerts["Alerts and audit<br/>[alerts-section.tsx]"]
  node_intelligence["Marketing intelligence"]
end

subgraph group_meta["Meta Ads"]
  node_meta_routes["Meta API routes"]
  node_meta_logic["Meta Graph integration<br/>[meta-api.ts]"]
  node_meta_service["Meta Ads platform"]
end

subgraph group_management["Workspace management"]
  node_clients["Client management"]
  node_connections["Connection management"]
  node_admin_ui["User administration<br/>[users-section.tsx]"]
  node_settings["Workspace settings"]
end

subgraph group_identity["Identity and storage"]
  node_auth["Session and role<br/>[auth-context.tsx]"]
  node_store_hook["Store data hooks<br/>[use-store.ts]"]
  node_store_route["Workspace store API<br/>[route.ts]"]
  node_admin_route["Admin user API<br/>[route.ts]"]
  node_me_route["Current-user API<br/>[route.ts]"]
  node_guard["Admin authorization<br/>[admin-guard.ts]"]
  node_supabase_browser["Browser Supabase client<br/>[client.ts]"]
  node_supabase_admin["Server Supabase client<br/>[admin.ts]"]
end

node_user(("Dashboard user"))
node_database[("Supabase database and auth")]

node_user -->|"opens"| node_page
node_page -->|"renders"| node_auth_ui
node_page -->|"renders"| node_dashboard
node_auth_ui -->|"signs in through"| node_auth
node_auth -->|"checks session"| node_supabase_browser
node_auth -->|"fetches role"| node_me_route
node_me_route -->|"gets requester"| node_guard
node_guard -->|"checks identity"| node_supabase_admin
node_dashboard -->|"renders"| node_overview
node_dashboard -->|"renders"| node_hierarchy
node_dashboard -->|"renders"| node_creatives
node_dashboard -->|"renders"| node_alerts
node_dashboard -->|"renders"| node_intelligence
node_filters -.->|"loads status and accounts"| node_meta_routes
node_meta_routes -->|"delegates to"| node_meta_logic
node_meta_logic -->|"reads connection token"| node_supabase_admin
node_meta_logic -->|"requests Graph API"| node_meta_service
node_clients -->|"creates and updates"| node_store_hook
node_connections -->|"manages connections"| node_store_hook
node_store_hook -->|"fetches and mutates"| node_store_route
node_store_route -->|"accesses records"| node_supabase_admin
node_admin_ui -.->|"administers users"| node_admin_route
node_settings -.->|"uses workspace data"| node_store_route
node_admin_route -->|"checks requester"| node_guard
node_admin_route -->|"reads and writes users"| node_supabase_admin
node_supabase_browser -.->|"authenticates"| node_database
node_supabase_admin -.->|"reads and writes"| node_database

click node_page "https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/page.tsx"
click node_auth_ui "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/auth/auth-screens.tsx"
click node_auth "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/auth-context.tsx"
click node_dashboard "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/dashboard-shell.tsx"
click node_filters "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/filters-context.tsx"
click node_overview "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/overview-section.tsx"
click node_hierarchy "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/hierarchy-section.tsx"
click node_creatives "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/creatives-section.tsx"
click node_alerts "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/alerts-section.tsx"
click node_intelligence "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/intelligence-section.tsx"
click node_meta_routes "https://github.com/alcalino100/dashboard-meta-ads/tree/main/app/api/meta"
click node_meta_logic "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/meta-api.ts"
click node_clients "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/clients-section.tsx"
click node_connections "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/connections-manager.tsx"
click node_admin_ui "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/users-section.tsx"
click node_settings "https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/settings-section.tsx"
click node_store_hook "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/use-store.ts"
click node_store_route "https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/api/store/%5Bentity%5D/route.ts"
click node_admin_route "https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/api/admin/users/route.ts"
click node_me_route "https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/api/me/route.ts"
click node_guard "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/admin-guard.ts"
click node_supabase_browser "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/supabase/client.ts"
click node_supabase_admin "https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/supabase/admin.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_page,node_auth_ui,node_dashboard,node_filters,node_overview,node_hierarchy,node_creatives,node_alerts,node_intelligence,node_user toneBlue
class node_meta_routes,node_meta_logic,node_meta_service,node_database toneAmber
class node_clients,node_connections,node_admin_ui,node_settings toneMint
class node_auth,node_store_hook,node_store_route,node_admin_route,node_me_route,node_guard,node_supabase_browser,node_supabase_admin toneRose
```

## Components

### Dashboard experience

- [App entry](https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/page.tsx): `app/page.tsx`
- [Sign-in screens](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/auth/auth-screens.tsx): `components/auth/auth-screens.tsx`
- [Dashboard shell](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/dashboard-shell.tsx): `components/dashboard/dashboard-shell.tsx`
- [Account and date filters](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/filters-context.tsx): `lib/filters-context.tsx`
- [Performance overview](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/overview-section.tsx): `components/dashboard/overview-section.tsx`
- [Campaign hierarchy](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/hierarchy-section.tsx): `components/dashboard/hierarchy-section.tsx`
- [Creative reporting](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/creatives-section.tsx): `components/dashboard/creatives-section.tsx`
- [Alerts and audit](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/alerts-section.tsx): `components/dashboard/alerts-section.tsx`
- [Marketing intelligence](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/intelligence-section.tsx): `components/dashboard/intelligence-section.tsx`

### Meta Ads

- [Meta API routes](https://github.com/alcalino100/dashboard-meta-ads/tree/main/app/api/meta): `app/api/meta`
- [Meta Graph integration](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/meta-api.ts): `lib/meta-api.ts`
- **Meta Ads platform**

### Workspace management

- [Client management](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/clients-section.tsx): `components/dashboard/clients-section.tsx`
- [Connection management](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/connections-manager.tsx): `components/dashboard/connections-manager.tsx`
- [User administration](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/users-section.tsx): `components/dashboard/users-section.tsx`
- [Workspace settings](https://github.com/alcalino100/dashboard-meta-ads/blob/main/components/dashboard/settings-section.tsx): `components/dashboard/settings-section.tsx`

### Identity and storage

- [Session and role](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/auth-context.tsx): `lib/auth-context.tsx`
- [Store data hooks](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/use-store.ts): `lib/use-store.ts`
- [Workspace store API](https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/api/store/%5Bentity%5D/route.ts): `app/api/store/[entity]/route.ts`
- [Admin user API](https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/api/admin/users/route.ts): `app/api/admin/users/route.ts`
- [Current-user API](https://github.com/alcalino100/dashboard-meta-ads/blob/main/app/api/me/route.ts): `app/api/me/route.ts`
- [Admin authorization](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/admin-guard.ts): `lib/admin-guard.ts`
- [Browser Supabase client](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/supabase/client.ts): `lib/supabase/client.ts`
- [Server Supabase client](https://github.com/alcalino100/dashboard-meta-ads/blob/main/lib/supabase/admin.ts): `lib/supabase/admin.ts`

### Other components

- **Dashboard user**
- **Supabase database and auth**

## Connections

- Dashboard user → App entry: opens
- App entry → Sign-in screens: renders (evidence: `app/page.tsx`)
- App entry → Dashboard shell: renders (evidence: `app/page.tsx`)
- Sign-in screens → Session and role: signs in through (evidence: `components/auth/auth-screens.tsx`)
- Session and role → Browser Supabase client: checks session (evidence: `lib/auth-context.tsx`)
- Session and role → Current-user API: fetches role (evidence: `lib/auth-context.tsx`)
- Current-user API → Admin authorization: gets requester (evidence: `app/api/me/route.ts`)
- Admin authorization → Server Supabase client: checks identity (evidence: `lib/admin-guard.ts`)
- Dashboard shell → Performance overview: renders (evidence: `components/dashboard/dashboard-shell.tsx`)
- Dashboard shell → Campaign hierarchy: renders (evidence: `components/dashboard/dashboard-shell.tsx`)
- Dashboard shell → Creative reporting: renders (evidence: `components/dashboard/dashboard-shell.tsx`)
- Dashboard shell → Alerts and audit: renders (evidence: `components/dashboard/dashboard-shell.tsx`)
- Dashboard shell → Marketing intelligence: renders (evidence: `components/dashboard/dashboard-shell.tsx`)
- Account and date filters → Meta API routes: loads status and accounts
- Meta API routes → Meta Graph integration: delegates to (evidence: `app/api/meta/overview/route.ts`)
- Meta Graph integration → Server Supabase client: reads connection token (evidence: `lib/meta-api.ts`)
- Meta Graph integration → Meta Ads platform: requests Graph API (evidence: `lib/meta-api.ts`)
- Client management → Store data hooks: creates and updates (evidence: `components/dashboard/clients-section.tsx`)
- Connection management → Store data hooks: manages connections (evidence: `components/dashboard/connections-manager.tsx`)
- Store data hooks → Workspace store API: fetches and mutates (evidence: `lib/use-store.ts`)
- Workspace store API → Server Supabase client: accesses records (evidence: `app/api/store/[entity]/route.ts`)
- User administration → Admin user API: administers users
- Workspace settings → Workspace store API: uses workspace data
- Admin user API → Admin authorization: checks requester (evidence: `app/api/admin/users/route.ts`)
- Admin user API → Server Supabase client: reads and writes users (evidence: `app/api/admin/users/route.ts`)
- Browser Supabase client → Supabase database and auth: authenticates
- Server Supabase client → Supabase database and auth: reads and writes