# yadnesh72/cybba-segment-automation architecture

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

- Interactive diagram: https://gitdiagram.com/yadnesh72/cybba-segment-automation
- Repository: https://github.com/yadnesh72/cybba-segment-automation

## Overview

Cybba Segment Automation is a full-stack tool for finding marketplace audience-segment gaps and producing submission-ready segment names, taxonomy, descriptions, and pricing. A user starts a feature-configurable run in the web app; the backend streams progress and rows, while the pipeline generates proposals, validates them, and enriches them before results can be explored, persisted, or downloaded. Separate UI branches provide comparison, suggestions, and analytics. The graph follows documented capabilities and indexed imports; several backend internals and routes were not excerpted, so uncertain call links are omitted.

Main entry points: [`backend/api.py`](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/api.py) (FastAPI routes), [`backend/src/pipeline.py`](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/pipeline.py) (Run orchestration), [`frontend/src/api.ts`](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/src/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/src/App.tsx) (Run and results UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_app["Run and results UI<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_segments_table["Segments table<br/>[SegmentsTable.tsx]"]
  node_comparison_ui["Comparison page<br/>[ComparisonPage.tsx]"]
  node_suggestions_ui["Suggestions page"]
  node_analytics_ui["Analytics page<br/>[AnalyticsPage.tsx]"]
end

subgraph group_run["Generation pipeline"]
  node_backend_api["FastAPI routes<br/>[api.py]"]
  node_pipeline["Run orchestration<br/>[pipeline.py]"]
  node_segment_model["Gap proposal model"]
end

subgraph group_enrich["Enrichment and validation"]
  node_validators["Proposal validation<br/>[validators.py]"]
  node_taxonomy["Taxonomy prediction<br/>[taxonomy_bundle.py]"]
  node_descriptions["Description generation"]
  node_pricing["Pricing inference<br/>[pricing_model.py]"]
end

subgraph group_insight["Exploration and persistence"]
  node_comparison["Catalog comparison<br/>[comparison.py]"]
  node_suggestions["Gap suggestions<br/>[suggestions.py]"]
  node_analytics["Run analytics<br/>[analytics.py]"]
  node_llm_analytics["Analytics analysis<br/>[llm_analytics.py]"]
  node_persistence[("Run persistence<br/>[persist.py]")]
end

node_user(("Platform user"))
node_ollama(("Ollama service"))

node_user -->|"starts runs"| node_app
node_app -->|"requests and streams"| node_api_client
node_app -->|"renders rows"| node_segments_table
node_api_client -->|"calls endpoints"| node_backend_api
node_backend_api -->|"runs pipeline"| node_pipeline
node_pipeline -->|"generates proposals"| node_segment_model
node_pipeline -->|"validates proposals"| node_validators
node_pipeline -->|"predicts taxonomy"| node_taxonomy
node_pipeline -->|"generates descriptions"| node_descriptions
node_pipeline -->|"infers prices"| node_pricing
node_descriptions -->|"requests generation"| node_ollama
node_backend_api -->|"stores run data"| node_persistence
node_api_client -->|"serves results"| node_comparison_ui
node_comparison_ui -->|"fetches matches"| node_backend_api
node_api_client -->|"serves suggestions"| node_suggestions_ui
node_suggestions_ui -->|"requests analysis"| node_api_client
node_backend_api -->|"routes requests"| node_suggestions
node_suggestions -->|"uses run results"| node_pipeline
node_api_client -->|"serves analytics"| node_analytics_ui
node_analytics_ui -->|"requests analytics"| node_backend_api
node_backend_api -->|"routes analytics"| node_analytics
node_analytics -->|"delegates analysis"| node_llm_analytics
node_backend_api -->|"routes catalog search"| node_comparison

click node_app "https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/src/api.ts"
click node_segments_table "https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/SegmentsTable.tsx"
click node_comparison_ui "https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/ComparisonPage.tsx"
click node_suggestions_ui "https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/SuggestionsPage.tsx"
click node_analytics_ui "https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/AnalyticsPage.tsx"
click node_backend_api "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/api.py"
click node_pipeline "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/pipeline.py"
click node_segment_model "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/segment_expansion_model.py"
click node_validators "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/validators.py"
click node_taxonomy "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/taxonomy_bundle.py"
click node_descriptions "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/llm_descriptions.py"
click node_pricing "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/pricing_model.py"
click node_comparison "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/comparison.py"
click node_suggestions "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/suggestions.py"
click node_analytics "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/analytics.py"
click node_llm_analytics "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/llm_analytics.py"
click node_persistence "https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/persist.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_api_client,node_segments_table,node_comparison_ui,node_suggestions_ui,node_analytics_ui,node_user toneBlue
class node_backend_api,node_pipeline,node_segment_model toneAmber
class node_validators,node_taxonomy,node_descriptions,node_pricing toneMint
class node_comparison,node_suggestions,node_analytics,node_llm_analytics,node_persistence toneRose
class node_ollama toneIndigo
```

## Components

### Web application

- [Run and results UI](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Segments table](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/SegmentsTable.tsx): `frontend/components/SegmentsTable.tsx`
- [Comparison page](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/ComparisonPage.tsx): `frontend/components/ComparisonPage.tsx`
- [Suggestions page](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/SuggestionsPage.tsx): `frontend/components/SuggestionsPage.tsx`
- [Analytics page](https://github.com/yadnesh72/cybba-segment-automation/blob/main/frontend/components/AnalyticsPage.tsx): `frontend/components/AnalyticsPage.tsx`

### Generation pipeline

- [FastAPI routes](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/api.py): `backend/api.py`
- [Run orchestration](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/pipeline.py): `backend/src/pipeline.py`
- [Gap proposal model](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/segment_expansion_model.py): `backend/src/segment_expansion_model.py`

### Enrichment and validation

- [Proposal validation](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/validators.py): `backend/src/validators.py`
- [Taxonomy prediction](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/taxonomy_bundle.py): `backend/src/taxonomy_bundle.py`
- [Description generation](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/llm_descriptions.py): `backend/src/llm_descriptions.py`
- [Pricing inference](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/pricing_model.py): `backend/src/pricing_model.py`

### Exploration and persistence

- [Catalog comparison](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/comparison.py): `backend/src/comparison.py`
- [Gap suggestions](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/suggestions.py): `backend/src/suggestions.py`
- [Run analytics](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/analytics.py): `backend/src/analytics.py`
- [Analytics analysis](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/llm_analytics.py): `backend/src/llm_analytics.py`
- [Run persistence](https://github.com/yadnesh72/cybba-segment-automation/blob/main/backend/src/persist.py): `backend/src/persist.py`

### Other components

- **Platform user**
- **Ollama service**

## Connections

- Platform user → Run and results UI: starts runs (evidence: `README.md`)
- Run and results UI → API client: requests and streams (evidence: `frontend/src/App.tsx`)
- Run and results UI → Segments table: renders rows (evidence: `frontend/src/App.tsx`)
- API client → FastAPI routes: calls endpoints (evidence: `frontend/src/api.ts`)
- FastAPI routes → Run orchestration: runs pipeline (evidence: `backend/api.py`)
- Run orchestration → Gap proposal model: generates proposals (evidence: `backend/src/pipeline.py`)
- Run orchestration → Proposal validation: validates proposals (evidence: `backend/src/pipeline.py`)
- Run orchestration → Taxonomy prediction: predicts taxonomy (evidence: `backend/src/pipeline.py`)
- Run orchestration → Description generation: generates descriptions (evidence: `backend/src/pipeline.py`)
- Run orchestration → Pricing inference: infers prices (evidence: `backend/src/pipeline.py`)
- Description generation → Ollama service: requests generation (evidence: `backend/src/llm_descriptions.py`)
- FastAPI routes → Run persistence: stores run data (evidence: `backend/api.py`)
- API client → Comparison page: serves results (evidence: `frontend/src/App.tsx`)
- Comparison page → FastAPI routes: fetches matches (evidence: `frontend/components/ComparisonPage.tsx`)
- API client → Suggestions page: serves suggestions (evidence: `frontend/src/App.tsx`)
- Suggestions page → API client: requests analysis (evidence: `frontend/components/SuggestionsPage.tsx`)
- FastAPI routes → Gap suggestions: routes requests (evidence: `backend/api.py`)
- Gap suggestions → Run orchestration: uses run results (evidence: `backend/src/suggestions.py`)
- API client → Analytics page: serves analytics (evidence: `frontend/src/App.tsx`)
- Analytics page → FastAPI routes: requests analytics (evidence: `frontend/components/AnalyticsPage.tsx`)
- FastAPI routes → Run analytics: routes analytics (evidence: `backend/api.py`)
- Run analytics → Analytics analysis: delegates analysis (evidence: `backend/src/analytics.py`)
- FastAPI routes → Catalog comparison: routes catalog search (evidence: `backend/api.py`)