# oguzhankayan/etsy-engine architecture

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

- Interactive diagram: https://gitdiagram.com/oguzhankayan/etsy-engine
- Repository: https://github.com/oguzhankayan/etsy-engine

## Overview

etsy-engine discovers Etsy product opportunities, validates demand and risk, designs printable or optional Canva products, generates and quality-checks assets, creates listing imagery and SEO, then prepares Etsy drafts. Its SQLite database preserves pipeline state and supports a post-publication learning loop. The README documents the major stages and optional Canva line; sampled source excerpts provide additional evidence for generation and storage behavior, while unsampled modules are represented only where documented.

Main entry points: [`src/etsy_engine/pipeline.py`](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/pipeline.py) (Discovery pipeline), [`src/etsy_engine/generate/generator.py`](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/generate/generator.py) (Page generation and QC), [`src/etsy_engine/generate/image_client.py`](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/generate/image_client.py) (Image client), [`src/etsy_engine/scoring`](https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/scoring) (Scoring and gates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Opportunity discovery"]
  node_sources["Trend sources"]
  node_ideas["Product ideas<br/>[product_ideas.py]"]
  node_funnel["Discovery pipeline<br/>[pipeline.py]"]
  node_scoring["Scoring and gates"]
  node_market["Etsy market research<br/>[etsy_market.py]"]
end

subgraph group_production["Product production"]
  node_architect["Bundle architect<br/>[architect.py]"]
  node_art["Art direction<br/>[art_director.py]"]
  node_generator["Page generation and QC<br/>[generator.py]"]
  node_imageclient["Image client<br/>[image_client.py]"]
end

subgraph group_listing["Listing and publishing"]
  node_mockups["Listing mockups<br/>[generator.py]"]
  node_seo["SEO listing copy<br/>[writer.py]"]
  node_publisher["Draft publisher<br/>[publisher.py]"]
end

subgraph group_operations["State and learning"]
  node_db[("SQLite product memory<br/>[db.py]")]
  node_learning["Metrics and learning"]
end

subgraph group_canva["Canva product line"]
  node_canva["Canva production<br/>[produce.py]"]
end

node_shopper(("Shop operator"))
node_cli["Command interface<br/>[__main__.py]"]
node_raywake["Raywake image service"]
node_etsy["Etsy service"]
node_anthropic["Anthropic models"]

node_shopper -->|"runs commands"| node_cli
node_cli -->|"starts stages"| node_funnel
node_funnel -->|"collects trends"| node_sources
node_funnel -->|"includes ideas"| node_ideas
node_funnel -->|"scores candidates"| node_scoring
node_funnel -->|"validates demand"| node_market
node_funnel -->|"plans bundles"| node_architect
node_architect -->|"reads market data"| node_market
node_funnel -->|"generates pages"| node_generator
node_generator -->|"uses art direction"| node_art
node_generator -->|"requests images"| node_imageclient
node_imageclient -->|"selects engine"| node_raywake
node_funnel -->|"creates mockups"| node_mockups
node_mockups -->|"generates scenes"| node_imageclient
node_funnel -->|"writes listing copy"| node_seo
node_funnel -->|"prepares drafts"| node_publisher
node_publisher -->|"creates drafts"| node_etsy
node_funnel -->|"persists stages"| node_db
node_learning -->|"reads metrics"| node_db
node_shopper -.->|"prepares templates"| node_canva
node_canva -.->|"generates imagery"| node_raywake
node_scoring -.->|"analyzes candidates"| node_anthropic
node_seo -.->|"drafts copy"| node_anthropic
node_generator -.->|"checks page quality"| node_anthropic

click node_cli "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/__main__.py"
click node_sources "https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/sources"
click node_ideas "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/product_ideas.py"
click node_funnel "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/pipeline.py"
click node_scoring "https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/scoring"
click node_market "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/scoring/etsy_market.py"
click node_architect "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/product/architect.py"
click node_art "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/design/art_director.py"
click node_generator "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/generate/generator.py"
click node_imageclient "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/generate/image_client.py"
click node_mockups "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/mockups/generator.py"
click node_seo "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/seo/writer.py"
click node_publisher "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/publish/publisher.py"
click node_db "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/db.py"
click node_learning "https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/learning"
click node_canva "https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/canva/produce.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_sources,node_ideas,node_funnel,node_scoring,node_market toneBlue
class node_architect,node_art,node_generator,node_imageclient toneAmber
class node_mockups,node_seo,node_publisher toneMint
class node_db,node_learning toneRose
class node_canva,node_shopper,node_raywake,node_etsy,node_anthropic toneIndigo
class node_cli toneTeal
```

## Components

### Opportunity discovery

- [Trend sources](https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/sources): `src/etsy_engine/sources`
- [Product ideas](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/product_ideas.py): `src/etsy_engine/product_ideas.py`
- [Discovery pipeline](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/pipeline.py): `src/etsy_engine/pipeline.py`
- [Scoring and gates](https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/scoring): `src/etsy_engine/scoring`
- [Etsy market research](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/scoring/etsy_market.py): `src/etsy_engine/scoring/etsy_market.py`

### Product production

- [Bundle architect](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/product/architect.py): `src/etsy_engine/product/architect.py`
- [Art direction](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/design/art_director.py): `src/etsy_engine/design/art_director.py`
- [Page generation and QC](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/generate/generator.py): `src/etsy_engine/generate/generator.py`
- [Image client](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/generate/image_client.py): `src/etsy_engine/generate/image_client.py`

### Listing and publishing

- [Listing mockups](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/mockups/generator.py): `src/etsy_engine/mockups/generator.py`
- [SEO listing copy](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/seo/writer.py): `src/etsy_engine/seo/writer.py`
- [Draft publisher](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/publish/publisher.py): `src/etsy_engine/publish/publisher.py`

### State and learning

- [SQLite product memory](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/db.py): `src/etsy_engine/db.py`
- [Metrics and learning](https://github.com/oguzhankayan/etsy-engine/tree/main/src/etsy_engine/learning): `src/etsy_engine/learning`

### Canva product line

- [Canva production](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/canva/produce.py): `src/etsy_engine/canva/produce.py`

### Other components

- **Shop operator**
- [Command interface](https://github.com/oguzhankayan/etsy-engine/blob/main/src/etsy_engine/__main__.py): `src/etsy_engine/__main__.py`
- **Raywake image service**
- **Etsy service**
- **Anthropic models**

## Connections

- Shop operator → Command interface: runs commands (evidence: `README.md`)
- Command interface → Discovery pipeline: starts stages (evidence: `README.md`)
- Discovery pipeline → Trend sources: collects trends (evidence: `README.md`)
- Discovery pipeline → Product ideas: includes ideas (evidence: `src/etsy_engine/pipeline.py`)
- Discovery pipeline → Scoring and gates: scores candidates (evidence: `README.md`)
- Discovery pipeline → Etsy market research: validates demand (evidence: `src/etsy_engine/pipeline.py`)
- Discovery pipeline → Bundle architect: plans bundles (evidence: `README.md`)
- Bundle architect → Etsy market research: reads market data (evidence: `src/etsy_engine/product/architect.py`)
- Discovery pipeline → Page generation and QC: generates pages (evidence: `README.md`)
- Page generation and QC → Art direction: uses art direction (evidence: `src/etsy_engine/generate/generator.py`)
- Page generation and QC → Image client: requests images (evidence: `src/etsy_engine/generate/generator.py`)
- Image client → Raywake image service: selects engine (evidence: `src/etsy_engine/generate/image_client.py`)
- Discovery pipeline → Listing mockups: creates mockups (evidence: `README.md`)
- Listing mockups → Image client: generates scenes (evidence: `src/etsy_engine/mockups/generator.py`)
- Discovery pipeline → SEO listing copy: writes listing copy (evidence: `README.md`)
- Discovery pipeline → Draft publisher: prepares drafts (evidence: `README.md`)
- Draft publisher → Etsy service: creates drafts
- Discovery pipeline → SQLite product memory: persists stages (evidence: `src/etsy_engine/pipeline.py`)
- Metrics and learning → SQLite product memory: reads metrics (evidence: `README.md`)
- Shop operator → Canva production: prepares templates (evidence: `README.md`)
- Canva production → Raywake image service: generates imagery
- Scoring and gates → Anthropic models: analyzes candidates (evidence: `README.md`)
- SEO listing copy → Anthropic models: drafts copy (evidence: `README.md`)
- Page generation and QC → Anthropic models: checks page quality (evidence: `README.md`)
