How shadow-0602/serp-scout works
Serp-Scout is a multi-tenant competitive-intelligence and local SEO action platform. A business owner uses the web app to manage a business and request research; background analysis extracts its profile, gathers local search evidence, and supports competitor and keyword opportunity analysis. Ranking changes and market shifts feed prioritized recommendations and reports, delivered in dashboards, PDFs, and email. The README documents additional audits, sharing, scheduling, and outcome tracking. Unsampled route and agent implementations are represented by their existing paths; their internal wiring is not inferred.
Main entry points: analysis.ts REST routes · index.ts Postgres data · search-run.service.ts Search runs · queues.ts Job queues
Components 26
Web experience
- Business dashboards
apps/web/src/app/(app)/app/page.tsx - Shared reports
apps/web/src/app/shared/[token]/page.tsx
API and analysis
- REST routes
apps/api/src/routes/analysis.ts - Search runs
apps/api/src/services/search-run.service.ts - Ranking deltas
apps/api/src/services/ranking.service.ts - Market alerts
apps/api/src/services/market-shift.service.ts - PDF rendering
apps/api/src/services/pdf.service.ts - Email notifications
apps/api/src/services/notification.service.ts
Intelligence agents
- Website analysis
packages/agents/src/website-analyzer/index.ts - Page extraction
packages/agents/src/website-analyzer/parser.ts - Competitor discovery
packages/agents/src/competitor-discovery/index.ts - Keyword opportunities
packages/agents/src/keyword-discovery/index.ts - Content gaps
packages/agents/src/content-gap/index.ts - Action recommendations
packages/agents/src/recommendation-engine/index.ts - Report generation
packages/agents/src/report-generator/index.ts
Background work
- Job queues
apps/api/src/jobs/queues.ts - Research worker
apps/api/src/jobs/workers/research.worker.ts - Report worker
apps/api/src/jobs/workers/report.worker.ts - Stale checks
apps/api/src/jobs/workers/stale-check.worker.ts
State and integrations
- Postgres data
packages/db/src/schema/index.ts - SerpApi search
packages/serpapi/src/index.ts - Tavily search
apps/api/src/services/tavily.service.ts - Redis queue state
apps/api/src/jobs/queues.ts
Other components
- Business owner
- Search provider
- Email delivery
Connections 30
- Business owner → Business dashboards: uses
- Business dashboards → REST routes: API requests
- Shared reports → REST routes: public access
- REST routes → Search runs: starts searches
- Search runs → Postgres data: reads and writes
- Search runs → SerpApi search: searches
- Search runs → Tavily search: searches
- SerpApi search → Search provider: queries
- Research worker → Website analysis: analyzes sites
- Website analysis → Page extraction: extracts pages
- Research worker → Ranking deltas: refreshes rankings
- Research worker → Postgres data: reads and updates
- REST routes → Job queues: enqueues work
- Job queues → Research worker: dispatches jobs
- Job queues → Report worker: dispatches jobs
- Job queues → Stale checks: dispatches jobs
- Job queues → Redis queue state: stores queue state
- Search runs → Market alerts: triggers analysis
- Report worker → Report generation: generates report
- Report worker → Postgres data: reads and saves
- Report worker → PDF rendering: renders report
- Report worker → Email notifications: requests delivery
- Email notifications → Postgres data: records notifications
- Email notifications → Email delivery: sends email
- REST routes → Competitor discovery: supports discovery
- REST routes → Keyword opportunities: supports discovery
- REST routes → Content gaps: supports analysis
- REST routes → Action recommendations: supports actions
- Ranking deltas → Postgres data: reads observations
- Stale checks → Postgres data: checks freshness