# peterquads/odylic-constellation architecture

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

- Interactive diagram: https://gitdiagram.com/peterquads/odylic-constellation
- Repository: https://github.com/peterquads/odylic-constellation

## Overview

Odylic Constellation is a local, read-only Meta Ads explorer. The user connects an account, chooses a date range, and the app loads ad data for a 3D creative space; selecting an ad opens metrics and on-demand charts. Separate capabilities include funnel and naming-based grouping, metric-axis layouts, creative variations, and group grid/slideshow views. Backend details beyond the excerpts are represented only where the README or SOURCE INDEX supports them; the API-to-Meta request flow is documented, but not every endpoint implementation was sampled.

Main entry points: [`web/src/App.tsx`](https://github.com/peterquads/odylic-constellation/blob/main/web/src/App.tsx) (App workflow), [`web/src/space/CreativeSpace3D.tsx`](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/CreativeSpace3D.tsx) (3D creative space), [`web/src/lib/api.ts`](https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/api.ts) (API client), [`api/main.py`](https://github.com/peterquads/odylic-constellation/blob/main/api/main.py) (API service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Ad exploration"]
  node_app["App workflow<br/>[App.tsx]"]
  node_onboarding["Account connection<br/>[Onboarding.tsx]"]
  node_header["Range and settings<br/>[Header.tsx]"]
  node_ads["Ad model and stacks<br/>[adModel.ts]"]
  node_detail["Ad detail drawer<br/>[AdDrawer.tsx]"]
  node_chartdata["Chart data requests<br/>[adCharts.ts]"]
  node_date["Date ranges<br/>[dateRanges.ts]"]
end

subgraph group_presentation["Space and insights"]
  node_naming["Name parsing<br/>[autoNaming.ts]"]
  node_funnel["Funnel ranking<br/>[funnelPosition.ts]"]
  node_layout["Grouping and layout<br/>[spaceLayout.ts]"]
  node_space["3D creative space"]
  node_engine["Canvas renderer<br/>[spaceEngine.ts]"]
  node_thumbs["Creative thumbnails<br/>[spaceThumbs.ts]"]
  node_groupviews["Group views<br/>[GroupGrid.tsx]"]
  node_variation["Variation stepping"]
  node_charts["Performance charts"]
end

subgraph group_service["Local service"]
  node_client["API client<br/>[api.ts]"]
  node_server["API service<br/>[main.py]"]
  node_meta["Meta Ads access<br/>[meta.py]"]
  node_governor["Rate governor<br/>[governor.py]"]
  node_demo["Demo account data<br/>[demo_data.py]"]
end

subgraph group_persistence["Local state"]
  node_store[("Config and cache<br/>[store.py]")]
end

node_user(("User"))
node_metaapi["Meta Graph API"]

node_user -->|"uses"| node_app
node_app -->|"opens connect"| node_onboarding
node_app -->|"shows controls"| node_header
node_onboarding -->|"connects through"| node_client
node_header -->|"sets range"| node_app
node_app -->|"loads data"| node_client
node_client -->|"requests"| node_server
node_server -->|"fetches account data"| node_meta
node_meta -->|"reads ads"| node_metaapi
node_meta -->|"passes requests through"| node_governor
node_server -->|"reads and writes"| node_store
node_server -->|"loads demo data"| node_demo
node_app -->|"enriches and stacks"| node_ads
node_app -->|"derives positions"| node_funnel
node_app -->|"renders cards"| node_space
node_space -->|"builds layouts"| node_layout
node_layout -->|"uses parsed fields"| node_naming
node_space -->|"drives rendering"| node_engine
node_space -->|"loads thumbnails"| node_thumbs
node_space -->|"offers alternatives"| node_groupviews
node_space -->|"steps variations"| node_variation
node_app -->|"opens selected ad"| node_detail
node_detail -->|"requests charts"| node_chartdata
node_chartdata -->|"uses API requests"| node_client
node_detail -->|"shows chart views"| node_charts
node_app -->|"selects default range"| node_date
node_client -.->|"fetches chart data"| node_metaapi

click node_app "https://github.com/peterquads/odylic-constellation/blob/main/web/src/App.tsx"
click node_onboarding "https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/Onboarding.tsx"
click node_header "https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/Header.tsx"
click node_client "https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/api.ts"
click node_server "https://github.com/peterquads/odylic-constellation/blob/main/api/main.py"
click node_meta "https://github.com/peterquads/odylic-constellation/blob/main/api/meta.py"
click node_governor "https://github.com/peterquads/odylic-constellation/blob/main/api/governor.py"
click node_store "https://github.com/peterquads/odylic-constellation/blob/main/api/store.py"
click node_ads "https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/adModel.ts"
click node_naming "https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/autoNaming.ts"
click node_funnel "https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/funnelPosition.ts"
click node_layout "https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/spaceLayout.ts"
click node_space "https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/CreativeSpace3D.tsx"
click node_engine "https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/spaceEngine.ts"
click node_thumbs "https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/spaceThumbs.ts"
click node_groupviews "https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/GroupGrid.tsx"
click node_variation "https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/VariationStepper.tsx"
click node_detail "https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/AdDrawer.tsx"
click node_chartdata "https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/adCharts.ts"
click node_charts "https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/charts/PerformanceCharts.tsx"
click node_date "https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/dateRanges.ts"
click node_demo "https://github.com/peterquads/odylic-constellation/blob/main/api/demo_data.py"

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_app,node_onboarding,node_header,node_ads,node_detail,node_chartdata,node_date,node_user toneBlue
class node_naming,node_funnel,node_layout,node_space,node_engine,node_thumbs,node_groupviews,node_variation,node_charts toneAmber
class node_client,node_server,node_meta,node_governor,node_demo,node_metaapi toneMint
class node_store toneRose
```

## Components

### Ad exploration

- [App workflow](https://github.com/peterquads/odylic-constellation/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Account connection](https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/Onboarding.tsx): `web/src/components/Onboarding.tsx`
- [Range and settings](https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/Header.tsx): `web/src/components/Header.tsx`
- [Ad model and stacks](https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/adModel.ts): `web/src/lib/adModel.ts`
- [Ad detail drawer](https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/AdDrawer.tsx): `web/src/components/AdDrawer.tsx`
- [Chart data requests](https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/adCharts.ts): `web/src/lib/adCharts.ts`
- [Date ranges](https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/dateRanges.ts): `web/src/lib/dateRanges.ts`

### Space and insights

- [Name parsing](https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/autoNaming.ts): `web/src/lib/autoNaming.ts`
- [Funnel ranking](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/funnelPosition.ts): `web/src/space/funnelPosition.ts`
- [Grouping and layout](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/spaceLayout.ts): `web/src/space/spaceLayout.ts`
- [3D creative space](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/CreativeSpace3D.tsx): `web/src/space/CreativeSpace3D.tsx`
- [Canvas renderer](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/spaceEngine.ts): `web/src/space/spaceEngine.ts`
- [Creative thumbnails](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/spaceThumbs.ts): `web/src/space/spaceThumbs.ts`
- [Group views](https://github.com/peterquads/odylic-constellation/blob/main/web/src/space/GroupGrid.tsx): `web/src/space/GroupGrid.tsx`
- [Variation stepping](https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/VariationStepper.tsx): `web/src/components/VariationStepper.tsx`
- [Performance charts](https://github.com/peterquads/odylic-constellation/blob/main/web/src/components/charts/PerformanceCharts.tsx): `web/src/components/charts/PerformanceCharts.tsx`

### Local service

- [API client](https://github.com/peterquads/odylic-constellation/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [API service](https://github.com/peterquads/odylic-constellation/blob/main/api/main.py): `api/main.py`
- [Meta Ads access](https://github.com/peterquads/odylic-constellation/blob/main/api/meta.py): `api/meta.py`
- [Rate governor](https://github.com/peterquads/odylic-constellation/blob/main/api/governor.py): `api/governor.py`
- [Demo account data](https://github.com/peterquads/odylic-constellation/blob/main/api/demo_data.py): `api/demo_data.py`

### Local state

- [Config and cache](https://github.com/peterquads/odylic-constellation/blob/main/api/store.py): `api/store.py`

### Other components

- **User**
- **Meta Graph API**

## Connections

- User → App workflow: uses (evidence: `README.md`)
- App workflow → Account connection: opens connect (evidence: `web/src/App.tsx`)
- App workflow → Range and settings: shows controls (evidence: `web/src/App.tsx`)
- Account connection → API client: connects through (evidence: `web/src/App.tsx`)
- Range and settings → App workflow: sets range (evidence: `web/src/App.tsx`)
- App workflow → API client: loads data (evidence: `web/src/App.tsx`)
- API client → API service: requests (evidence: `web/src/lib/api.ts`)
- API service → Meta Ads access: fetches account data (evidence: `api/main.py`)
- Meta Ads access → Meta Graph API: reads ads (evidence: `README.md`)
- Meta Ads access → Rate governor: passes requests through (evidence: `api/meta.py`)
- API service → Config and cache: reads and writes (evidence: `api/main.py`)
- API service → Demo account data: loads demo data (evidence: `api/main.py`)
- App workflow → Ad model and stacks: enriches and stacks (evidence: `web/src/App.tsx`)
- App workflow → Funnel ranking: derives positions (evidence: `web/src/App.tsx`)
- App workflow → 3D creative space: renders cards (evidence: `web/src/App.tsx`)
- 3D creative space → Grouping and layout: builds layouts (evidence: `web/src/space/CreativeSpace3D.tsx`)
- Grouping and layout → Name parsing: uses parsed fields (evidence: `web/src/space/spaceLayout.ts`)
- 3D creative space → Canvas renderer: drives rendering (evidence: `web/src/space/CreativeSpace3D.tsx`)
- 3D creative space → Creative thumbnails: loads thumbnails (evidence: `web/src/space/CreativeSpace3D.tsx`)
- 3D creative space → Group views: offers alternatives (evidence: `README.md`)
- 3D creative space → Variation stepping: steps variations (evidence: `README.md`)
- App workflow → Ad detail drawer: opens selected ad (evidence: `README.md`)
- Ad detail drawer → Chart data requests: requests charts (evidence: `web/src/lib/adCharts.ts`)
- Chart data requests → API client: uses API requests (evidence: `web/src/lib/adCharts.ts`)
- Ad detail drawer → Performance charts: shows chart views (evidence: `README.md`)
- App workflow → Date ranges: selects default range (evidence: `web/src/App.tsx`)
- API client → Meta Graph API: fetches chart data