# krusemediallc/arcads-claude-code architecture

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

- Interactive diagram: https://gitdiagram.com/krusemediallc/arcads-claude-code
- Repository: https://github.com/krusemediallc/arcads-claude-code

## Overview

This repository is an AI-editor skill pack for producing marketing creatives with Arcads and other image/video models, researching competitor and account ads, and optionally publishing ads to Meta. The main creative workflow is agent-directed prompting, generation, and retrieval of outputs; separate branches handle animated-video assembly and Meta ad research, import, and deployment. The README documents capabilities beyond the sampled scripts, so those are represented at their documented skill or directory paths. Some subsystem internals were not sampled; their links are included only where documentation supports them.

Main entry points: [`shared/skills/meta-ad-builder/scripts/lib/meta_api.py`](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/lib/meta_api.py) (Meta API helpers), [`shared/skills/meta-ad-builder/scripts/deploy-ad.py`](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/deploy-ad.py) (Ad deployment), [`scripts/meta-ad-library-import/import_ads.py`](https://github.com/krusemediallc/arcads-claude-code/blob/main/scripts/meta-ad-library-import/import_ads.py) (Ad Library import), [`skills/chatgpt-image-ad/scripts/generate_image.py`](https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/chatgpt-image-ad/scripts/generate_image.py) (ChatGPT Image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creative["Creative generation"]
  node_arcads["Arcads workflows<br/>[SKILL.md]"]
  node_chatgpt_image["ChatGPT Image<br/>[generate_image.py]"]
  node_nano_image["Nano Banana<br/>[generate_image.py]"]
end

subgraph group_prompts["Prompt resources"]
  node_video_prompts["Video prompt library"]
  node_image_prompts["Image-ad prompts"]
end

subgraph group_video["Video production"]
  node_pixar["Pixar-style ads"]
  node_claymation["Claymation ads"]
  node_caption_video["Caption video"]
  node_caption_renderer["Caption renderer<br/>[render-captions.py]"]
end

subgraph group_meta["Meta research and ads"]
  node_competitor_ads["Competitor ad research"]
  node_top_ads["Top-ad analysis<br/>[pull-top-ads.py]"]
  node_meta_helpers["Meta API helpers<br/>[meta_api.py]"]
  node_deploy_ads["Ad deployment<br/>[deploy-ad.py]"]
end

subgraph group_swipe["Swipe-file import"]
  node_ad_library_import["Ad Library import<br/>[import_ads.py]"]
  node_reviewed_ads["Reviewed ad records"]
end

node_creator(("Creator / agent"))
node_arcads_service["Arcads API"]
node_creative_files["Generated creatives"]
node_video_assets["Assembled video"]
node_meta_api["Meta Marketing API"]
node_airtable[("Airtable")]
node_meta_library["Meta Ad Library"]

node_creator -->|"requests creation"| node_arcads
node_arcads -->|"uses prompts"| node_video_prompts
node_creator -->|"requests image"| node_chatgpt_image
node_creator -->|"requests image"| node_nano_image
node_image_prompts -.->|"guides prompting"| node_chatgpt_image
node_image_prompts -.->|"guides prompting"| node_nano_image
node_chatgpt_image -->|"submits and polls"| node_arcads_service
node_nano_image -->|"submits and polls"| node_arcads_service
node_arcads_service -.->|"returns images"| node_creative_files
node_creator -->|"requests animation"| node_pixar
node_creator -->|"requests animation"| node_claymation
node_creator -->|"requests captions"| node_caption_video
node_caption_video -.->|"renders captions"| node_caption_renderer
node_pixar -.->|"assembles video"| node_video_assets
node_creator -->|"requests research"| node_competitor_ads
node_creator -->|"requests analysis"| node_top_ads
node_competitor_ads -->|"uses helpers"| node_meta_helpers
node_top_ads -->|"uses helpers"| node_meta_helpers
node_deploy_ads -->|"uses helpers"| node_meta_helpers
node_meta_helpers -.->|"calls API"| node_meta_api
node_creator -->|"requests deployment"| node_deploy_ads
node_deploy_ads -->|"creates paused ads"| node_meta_api
node_creator -->|"requests import"| node_ad_library_import
node_ad_library_import -->|"discovers ads"| node_meta_library
node_ad_library_import -->|"extracts and reviews"| node_reviewed_ads
node_reviewed_ads -->|"imports records"| node_airtable

click node_arcads "https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/arcads-external-api/SKILL.md"
click node_video_prompts "https://github.com/krusemediallc/arcads-claude-code/tree/main/skills/arcads-external-api/prompting/prompt-library"
click node_image_prompts "https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/image-ad-prompting"
click node_chatgpt_image "https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/chatgpt-image-ad/scripts/generate_image.py"
click node_nano_image "https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/nano-banana-image-ad/scripts/generate_image.py"
click node_pixar "https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/pixar-style-ad/scripts"
click node_claymation "https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/claymation-ad"
click node_caption_video "https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/caption-video"
click node_caption_renderer "https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/pixar-style-ad/scripts/render-captions.py"
click node_competitor_ads "https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/pull-competitor-ads.py"
click node_top_ads "https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/pull-top-ads.py"
click node_meta_helpers "https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/lib/meta_api.py"
click node_deploy_ads "https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/deploy-ad.py"
click node_ad_library_import "https://github.com/krusemediallc/arcads-claude-code/blob/main/scripts/meta-ad-library-import/import_ads.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_arcads,node_chatgpt_image,node_nano_image toneBlue
class node_video_prompts,node_image_prompts,node_airtable toneAmber
class node_pixar,node_claymation,node_caption_video,node_caption_renderer,node_arcads_service,node_meta_api toneMint
class node_competitor_ads,node_top_ads,node_meta_helpers,node_deploy_ads toneRose
class node_ad_library_import,node_reviewed_ads,node_creator,node_creative_files,node_video_assets,node_meta_library toneIndigo
```

## Components

### Creative generation

- [Arcads workflows](https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/arcads-external-api/SKILL.md): `skills/arcads-external-api/SKILL.md`
- [ChatGPT Image](https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/chatgpt-image-ad/scripts/generate_image.py): `skills/chatgpt-image-ad/scripts/generate_image.py`
- [Nano Banana](https://github.com/krusemediallc/arcads-claude-code/blob/main/skills/nano-banana-image-ad/scripts/generate_image.py): `skills/nano-banana-image-ad/scripts/generate_image.py`

### Prompt resources

- [Video prompt library](https://github.com/krusemediallc/arcads-claude-code/tree/main/skills/arcads-external-api/prompting/prompt-library): `skills/arcads-external-api/prompting/prompt-library`
- [Image-ad prompts](https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/image-ad-prompting): `shared/skills/image-ad-prompting`

### Video production

- [Pixar-style ads](https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/pixar-style-ad/scripts): `shared/skills/pixar-style-ad/scripts`
- [Claymation ads](https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/claymation-ad): `shared/skills/claymation-ad`
- [Caption video](https://github.com/krusemediallc/arcads-claude-code/tree/main/shared/skills/caption-video): `shared/skills/caption-video`
- [Caption renderer](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/pixar-style-ad/scripts/render-captions.py): `shared/skills/pixar-style-ad/scripts/render-captions.py`

### Meta research and ads

- [Competitor ad research](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/pull-competitor-ads.py): `shared/skills/meta-ad-builder/scripts/pull-competitor-ads.py`
- [Top-ad analysis](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/pull-top-ads.py): `shared/skills/meta-ad-builder/scripts/pull-top-ads.py`
- [Meta API helpers](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/lib/meta_api.py): `shared/skills/meta-ad-builder/scripts/lib/meta_api.py`
- [Ad deployment](https://github.com/krusemediallc/arcads-claude-code/blob/main/shared/skills/meta-ad-builder/scripts/deploy-ad.py): `shared/skills/meta-ad-builder/scripts/deploy-ad.py`

### Swipe-file import

- [Ad Library import](https://github.com/krusemediallc/arcads-claude-code/blob/main/scripts/meta-ad-library-import/import_ads.py): `scripts/meta-ad-library-import/import_ads.py`
- **Reviewed ad records**

### Other components

- **Creator / agent**
- **Arcads API**
- **Generated creatives**
- **Assembled video**
- **Meta Marketing API**
- **Airtable**
- **Meta Ad Library**

## Connections

- Creator / agent → Arcads workflows: requests creation (evidence: `README.md`)
- Arcads workflows → Video prompt library: uses prompts (evidence: `README.md`)
- Creator / agent → ChatGPT Image: requests image (evidence: `README.md`)
- Creator / agent → Nano Banana: requests image (evidence: `README.md`)
- Image-ad prompts → ChatGPT Image: guides prompting
- Image-ad prompts → Nano Banana: guides prompting
- ChatGPT Image → Arcads API: submits and polls (evidence: `skills/chatgpt-image-ad/scripts/generate_image.py`)
- Nano Banana → Arcads API: submits and polls (evidence: `skills/nano-banana-image-ad/scripts/generate_image.py`)
- Arcads API → Generated creatives: returns images
- Creator / agent → Pixar-style ads: requests animation (evidence: `README.md`)
- Creator / agent → Claymation ads: requests animation (evidence: `README.md`)
- Creator / agent → Caption video: requests captions (evidence: `README.md`)
- Caption video → Caption renderer: renders captions
- Pixar-style ads → Assembled video: assembles video
- Creator / agent → Competitor ad research: requests research (evidence: `README.md`)
- Creator / agent → Top-ad analysis: requests analysis (evidence: `README.md`)
- Competitor ad research → Meta API helpers: uses helpers (evidence: `shared/skills/meta-ad-builder/scripts/pull-competitor-ads.py`)
- Top-ad analysis → Meta API helpers: uses helpers (evidence: `shared/skills/meta-ad-builder/scripts/pull-top-ads.py`)
- Ad deployment → Meta API helpers: uses helpers (evidence: `shared/skills/meta-ad-builder/scripts/deploy-ad.py`)
- Meta API helpers → Meta Marketing API: calls API
- Creator / agent → Ad deployment: requests deployment (evidence: `README.md`)
- Ad deployment → Meta Marketing API: creates paused ads (evidence: `shared/skills/meta-ad-builder/scripts/deploy-ad.py`)
- Creator / agent → Ad Library import: requests import (evidence: `README.md`)
- Ad Library import → Meta Ad Library: discovers ads (evidence: `README.md`)
- Ad Library import → Reviewed ad records: extracts and reviews (evidence: `README.md`)
- Reviewed ad records → Airtable: imports records (evidence: `README.md`)
