technology-ai-cogni/seo-backend

Purpose and Entry Points

This repository is an SEO keyword-research, categorization, ranking, and dashboard system. It combines a Python backend that processes uploaded keyword CSVs and retrieves ranking/category data with a Vite/React dashboard for project and SEO-analysis views.

Primary runtime entry points are backend/app.py for the API service, backend/scripts/run_pipeline.py and backend/scripts/run_pipeline_brightdata.py for batch processing, and frontend/seo-dashboard/src/main.jsx for the browser application.

Backend API and Persistence Boundary

The backend exposes application behavior from backend/app.py, with database setup/access isolated in backend/core/db.py. Service-layer modules separate API-facing operations from ranking and category-checking logic:

• backend/services/rank_checker.py

• backend/services/category_checker.py

• backend/core/db.py

This is the main boundary between client/API requests, persisted project or analysis state, and external SEO-data retrieval.

Keyword Processing Pipeline

CSV datasets are the primary input/output contract. Source and generated files live under backend/datasets/ and backend/datasets/uploads/, including pipeline-enriched CSVs. Pipeline orchestration is represented by:

• backend/scripts/run_pipeline.py

• backend/scripts/run_pipeline_brightdata.py

• backend/scripts/category_assigner.py

The flow is: ingest keyword sheet → retrieve/search-enrich data → classify intent, landing/blog suitability, and categories/clusters → write enriched pipeline artifacts for downstream API/dashboard consumption.

Search, Ranking, and Competitive Analysis

Ranking and SERP collection are implemented as dedicated scripts/services rather than frontend logic:

• backend/scripts/serp_scraper.py

• backend/scripts/agentic_rank_checker.py

• backend/scripts/comp_analysis.py

backend/scripts/hosted_rank_check.py and backend/scripts/hosted_categorize.py indicate hosted/external execution paths, while backend/scripts/run_pipeline_brightdata.py signals Bright Data-backed collection. These integrations are material external-service boundaries and should be treated as failure-prone, rate-limited stages with normalized outputs before persistence.

Experimental Category Intelligence

A more granular category pipeline exists independently under backend/scripts/exp_category_pipeline/. Its stages divide classification, SERP retrieval, metadata collection, clustering, grouping, naming, and recategorization:

• backend/scripts/exp_category_pipeline/run_experiment.py

• backend/scripts/exp_category_pipeline/serp_fetch.py

• backend/scripts/exp_category_pipeline/metadata_fetch.py

• backend/scripts/exp_category_pipeline/classifiers.py

• backend/scripts/exp_category_pipeline/cluster_grouper.py

• backend/scripts/exp_category_pipeline/sequential_recategorize.py

This is an analysis pipeline boundary: it transforms raw keyword/search evidence into structured category and cluster assignments, likely producing candidate logic for the main pipeline.

Frontend Dashboard

The frontend is a Vite React single-page application rooted at frontend/seo-dashboard/src/main.jsx and frontend/seo-dashboard/src/App.jsx. Shared navigation/layout is centralized in:

• frontend/seo-dashboard/src/components/layout/Sidebar.jsx

• frontend/seo-dashboard/src/components/layout/Topbar.jsx

• frontend/seo-dashboard/src/data/navigation.js

Feature pages cover dashboarding, keyword analysis, positions, competitors, top pages, AI visibility, and content planning. Core views include frontend/seo-dashboard/src/components/pages/KeywordsPage.jsx, frontend/seo-dashboard/src/components/pages/PositionAnalysisPage.jsx, and frontend/seo-dashboard/src/components/pages/ContentEnginePage.jsx.

Client Data Sources and Infrastructure

The dashboard has both local/demo and remote-data paths. CSV parsing and mock datasets are in frontend/seo-dashboard/src/data/csvParser.js and frontend/seo-dashboard/src/data/mockData.js; project access is abstracted by frontend/seo-dashboard/src/lib/projectsApi.js. frontend/seo-dashboard/src/lib/supabaseClient.js identifies Supabase as a client-side backend/service integration.

Deployment/runtime packaging is split between a Dockerized Python backend (backend/Dockerfile) and the Node/Vite frontend (frontend/seo-dashboard/package.json). The key architectural concern is keeping CSV/batch pipeline artifacts, backend database records, Supabase project data, and dashboard models consistent rather than allowing each path to become an independent source of truth.