# thehypedge/riviso_seo architecture

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

- Interactive diagram: https://gitdiagram.com/thehypedge/riviso_seo
- Repository: https://github.com/thehypedge/riviso_seo

## Overview

The tree describes Riviso, an SEO content-operations application, rather than the Gitleaks tool described by the supplied README; I use the tree and sampled source as the architecture evidence. The primary workflow is a user creating an article in the web app, sending a request to the API, and having the article pipeline generate and persist it. Other visible capabilities include WordPress and Shopify publishing context, AI citation tracking, research, SEO audits, and search-console services. Several subsystems are unsampled, so their internal wiring is not inferred.

Main entry points: [`backend/app/services/article_pipeline.py`](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/article_pipeline.py) (Article generation), [`backend/app/api/router.py`](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/router.py) (API router), [`backend/app/services/ai_citation/runner.py`](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/runner.py) (Citation runner), [`frontend/src/app/projects/[projectId]/articles/[articleId]/page.tsx`](https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/app/projects/%5BprojectId%5D/articles/%5BarticleId%5D/page.tsx) (Article workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Riviso web app<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_article_ui["Article workspace<br/>[page.tsx]"]
  node_pipeline_monitor["Pipeline monitor<br/>[pipelineStream.ts]"]
end

subgraph group_api["API and persistence"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_article_routes["Article endpoints<br/>[articles.py]"]
  node_storage[("Application storage<br/>[storage.py]")]
end

subgraph group_content["Content operations"]
  node_article_pipeline["Article generation"]
  node_generation["AI generation"]
  node_generation_worker["Generation worker"]
end

subgraph group_insights["SEO and research"]
  node_citation_routes["AI citation API<br/>[ai_citation.py]"]
  node_citation_runner["Citation runner<br/>[runner.py]"]
  node_citation_google["Google AI Overview"]
  node_citation_gemini["Gemini search<br/>[gemini_engine.py]"]
  node_citation_perplexity["Perplexity search"]
  node_seo_routes["Site audit API<br/>[site_audit_seo.py]"]
  node_seo_worker["SEO crawl worker"]
  node_research_routes["Research API<br/>[research.py]"]
  node_research_runner["Research jobs"]
end

subgraph group_integrations["External platforms"]
  node_wordpress_pipeline["WordPress context"]
  node_shopify_pipeline["Shopify context"]
  node_wordpress_publish["WordPress publishing"]
  node_shopify_sync["Shopify sync<br/>[shopify_sync.py]"]
end

node_user(("Content operator"))
node_openai(("OpenAI service"))
node_google(("Google services"))
node_perplexity(("Perplexity API"))
node_wordpress(("WordPress site"))
node_shopify(("Shopify store"))

node_user -->|"uses"| node_webapp
node_webapp -->|"opens"| node_article_ui
node_article_ui -->|"requests"| node_api_client
node_api_client -->|"calls"| node_api_entry
node_api_entry -->|"dispatches"| node_api_router
node_api_router -->|"dispatches"| node_article_routes
node_article_routes -->|"invokes"| node_article_pipeline
node_article_pipeline -->|"generates"| node_generation
node_generation -.->|"requests"| node_openai
node_article_pipeline -->|"persists"| node_storage
node_article_pipeline -->|"loads context"| node_wordpress_pipeline
node_article_pipeline -->|"loads context"| node_shopify_pipeline
node_article_pipeline -.->|"publishes"| node_wordpress_publish
node_article_pipeline -.->|"syncs"| node_shopify_sync
node_article_ui -->|"monitors"| node_pipeline_monitor
node_pipeline_monitor -->|"streams events"| node_api_entry
node_api_router -->|"dispatches"| node_citation_routes
node_citation_routes -->|"runs checks"| node_citation_runner
node_citation_runner -->|"checks"| node_citation_google
node_citation_runner -->|"checks"| node_citation_gemini
node_citation_runner -->|"checks"| node_citation_perplexity
node_citation_google -.->|"renders search"| node_google
node_citation_gemini -.->|"queries"| node_google
node_citation_perplexity -.->|"queries"| node_perplexity
node_api_router -->|"dispatches"| node_seo_routes
node_seo_routes -->|"starts crawl"| node_seo_worker
node_api_router -->|"dispatches"| node_research_routes
node_research_routes -->|"starts jobs"| node_research_runner
node_wordpress_publish -.->|"publishes to"| node_wordpress
node_shopify_sync -.->|"syncs with"| node_shopify

click node_webapp "https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/app/dashboard/page.tsx"
click node_api_client "https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/lib/api.ts"
click node_article_ui "https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/app/projects/%5BprojectId%5D/articles/%5BarticleId%5D/page.tsx"
click node_pipeline_monitor "https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/lib/pipelineStream.ts"
click node_api_entry "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/main.py"
click node_api_router "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/router.py"
click node_article_routes "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/articles.py"
click node_storage "https://github.com/thehypedge/riviso_seo/blob/main/storage.py"
click node_article_pipeline "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/article_pipeline.py"
click node_generation "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/article_generation.py"
click node_generation_worker "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/generation_worker.py"
click node_wordpress_pipeline "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/wordpress_content_pipeline.py"
click node_shopify_pipeline "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/shopify_product_pipeline.py"
click node_wordpress_publish "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/wordpress_publish.py"
click node_shopify_sync "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/shopify_sync.py"
click node_citation_routes "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/ai_citation.py"
click node_citation_runner "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/runner.py"
click node_citation_google "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/google_ai_overview_engine.py"
click node_citation_gemini "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/gemini_engine.py"
click node_citation_perplexity "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/perplexity_engine.py"
click node_seo_routes "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/site_audit_seo.py"
click node_seo_worker "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/seo_crawl_worker.py"
click node_research_routes "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/research.py"
click node_research_runner "https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/research_job_runner.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_webapp,node_api_client,node_article_ui,node_pipeline_monitor toneBlue
class node_api_entry,node_api_router,node_article_routes,node_storage toneAmber
class node_article_pipeline,node_generation,node_generation_worker,node_perplexity toneMint
class node_citation_routes,node_citation_runner,node_citation_google,node_citation_gemini,node_citation_perplexity,node_seo_routes,node_seo_worker,node_research_routes,node_research_runner toneRose
class node_wordpress_pipeline,node_shopify_pipeline,node_wordpress_publish,node_shopify_sync,node_user,node_openai,node_google,node_wordpress,node_shopify toneIndigo
```

## Components

### Web application

- [Riviso web app](https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/app/dashboard/page.tsx): `frontend/src/app/dashboard/page.tsx`
- [API client](https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Article workspace](https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/app/projects/%5BprojectId%5D/articles/%5BarticleId%5D/page.tsx): `frontend/src/app/projects/[projectId]/articles/[articleId]/page.tsx`
- [Pipeline monitor](https://github.com/thehypedge/riviso_seo/blob/main/frontend/src/lib/pipelineStream.ts): `frontend/src/lib/pipelineStream.ts`

### API and persistence

- [FastAPI application](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Article endpoints](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/articles.py): `backend/app/api/routes/articles.py`
- [Application storage](https://github.com/thehypedge/riviso_seo/blob/main/storage.py): `storage.py`

### Content operations

- [Article generation](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/article_pipeline.py): `backend/app/services/article_pipeline.py`
- [AI generation](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/article_generation.py): `backend/app/services/article_generation.py`
- [Generation worker](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/generation_worker.py): `backend/app/services/generation_worker.py`

### SEO and research

- [AI citation API](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/ai_citation.py): `backend/app/api/routes/ai_citation.py`
- [Citation runner](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/runner.py): `backend/app/services/ai_citation/runner.py`
- [Google AI Overview](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/google_ai_overview_engine.py): `backend/app/services/ai_citation/google_ai_overview_engine.py`
- [Gemini search](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/gemini_engine.py): `backend/app/services/ai_citation/gemini_engine.py`
- [Perplexity search](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/ai_citation/perplexity_engine.py): `backend/app/services/ai_citation/perplexity_engine.py`
- [Site audit API](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/site_audit_seo.py): `backend/app/api/routes/site_audit_seo.py`
- [SEO crawl worker](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/seo_crawl_worker.py): `backend/app/services/seo_crawl_worker.py`
- [Research API](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/api/routes/research.py): `backend/app/api/routes/research.py`
- [Research jobs](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/research_job_runner.py): `backend/app/services/research_job_runner.py`

### External platforms

- [WordPress context](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/wordpress_content_pipeline.py): `backend/app/services/wordpress_content_pipeline.py`
- [Shopify context](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/shopify_product_pipeline.py): `backend/app/services/shopify_product_pipeline.py`
- [WordPress publishing](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/wordpress_publish.py): `backend/app/services/wordpress_publish.py`
- [Shopify sync](https://github.com/thehypedge/riviso_seo/blob/main/backend/app/services/shopify_sync.py): `backend/app/services/shopify_sync.py`

### Other components

- **Content operator**
- **OpenAI service**
- **Google services**
- **Perplexity API**
- **WordPress site**
- **Shopify store**

## Connections

- Content operator → Riviso web app: uses
- Riviso web app → Article workspace: opens
- Article workspace → API client: requests
- API client → FastAPI application: calls
- FastAPI application → API router: dispatches
- API router → Article endpoints: dispatches
- Article endpoints → Article generation: invokes
- Article generation → AI generation: generates
- AI generation → OpenAI service: requests
- Article generation → Application storage: persists
- Article generation → WordPress context: loads context
- Article generation → Shopify context: loads context
- Article generation → WordPress publishing: publishes
- Article generation → Shopify sync: syncs
- Article workspace → Pipeline monitor: monitors
- Pipeline monitor → FastAPI application: streams events
- API router → AI citation API: dispatches
- AI citation API → Citation runner: runs checks
- Citation runner → Google AI Overview: checks
- Citation runner → Gemini search: checks
- Citation runner → Perplexity search: checks
- Google AI Overview → Google services: renders search
- Gemini search → Google services: queries
- Perplexity search → Perplexity API: queries
- API router → Site audit API: dispatches
- Site audit API → SEO crawl worker: starts crawl
- API router → Research API: dispatches
- Research API → Research jobs: starts jobs
- WordPress publishing → WordPress site: publishes to
- Shopify sync → Shopify store: syncs with