# nishal77/localseobot architecture

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

- Interactive diagram: https://gitdiagram.com/nishal77/localseobot
- Repository: https://github.com/nishal77/localseobot

## Overview

1. This repository is a Next.js App Router application that combines a customer-facing dashboard with a substantial server-side API and a separate background worker layer. It is not just a UI app; it behaves like a SaaS backend/frontend monolith plus async job runner.

2. The browser-facing surface lives under `src/app`. There are public/auth pages (`/`, `/login`, `/signup`), an onboarding flow, and the authenticated dashboard area with sections for citations, posts, rankings, reports, reviews, and settings. `src/app/layout.tsx`, `src/app/globals.css`, and the shared UI components support the overall shell.

3. The backend is exposed through many route handlers in `src/app/api`, organized by domain rather than by generic CRUD. The main API boundaries are auth, onboarding, dashboard metrics, citations, posts, rankings, reports, reviews, settings, billing, and webhooks. This structure suggests the frontend mostly talks to its own internal API rather than directly to database or external services.

4. Persistence is centralized through Prisma. `prisma/schema.prisma`, `prisma.config.ts`, `src/lib/prisma.ts`, and `prisma/seed.ts` indicate a relational database as the system of record for users, businesses, content, reports, rankings, reviews, and job state. The rest of the app appears to treat Prisma as the shared data access boundary.

5. There is a distinct asynchronous processing subsystem under `workers/`. `workers/index.ts`, `workers/scheduler.ts`, and the processor files show queued or scheduled background jobs for report generation, review polling/responding, ranking checks, competitor monitoring, onboarding audits, citation submission, and GBP post generation/publishing. This is the main non-request-driven execution path in the architecture.

6. The product domain appears centered on local SEO / reputation management. The dashboard sections and worker names point to business-profile management, review handling, ranking tracking, citation building, and content/post automation. The app likely aggregates data from external sources into internal reports and operational workflows.

7. Google Business Profile is a key external integration. The onboarding and settings routes for GBP connect/callback/reconnect, plus post generation/publishing and review workflows, imply OAuth-style connection management and ongoing API access to a business’s profile. This integration is likely one of the main reasons the system needs both webhooks and background jobs.

8. Billing and account lifecycle are handled separately from the core product flows. `src/app/api/billing/*` and `src/app/api/webhooks/whop/route.ts` indicate an external billing platform integration, likely used to activate, suspend, or provision access. The settings/billing dashboard page is the user-facing boundary for that subsystem.

9. Authentication is handled with NextAuth. `src/auth.ts` and `src/app/api/auth/[...nextauth]/route.ts` define the session/auth boundary, while `src/middleware.ts` likely protects dashboard and API routes. Signup is custom (`/api/auth/signup`), suggesting the app may blend credentials and provider-based auth.

10. AI-assisted generation is a notable service dependency. `src/lib/anthropic.ts` implies the app uses Anthropic to generate or assist with content such as GBP posts, reports, or response drafts. That AI layer is probably invoked from workers or server routes rather than directly from the client.

11. Supporting libraries show the main shared runtime boundaries: `src/lib/queue.ts` for async dispatch, `src/lib/gbp.ts` for profile API interactions, `src/lib/audit.ts` for onboarding checks, `src/lib/crypto.ts` for sensitive data handling, and `src/lib/utils.ts` for shared helpers. These are the glue between request handlers, workers, and external APIs.

12. The UI is built from a small custom component set plus reusable dashboard widgets. `src/components/ui/*` provides the design system primitives, while `src/components/dashboard/*` contains page-specific controls like bot settings, post actions, and the sidebar. This keeps presentation concerns separate from the domain/API logic.

13. Overall data flow is: user logs in, completes onboarding, connects GBP and billing, then the dashboard reads from internal APIs backed by Prisma. Scheduled or queued workers continuously fetch, generate, or update domain data, and the dashboard surfaces the latest state and history. Webhooks and callback routes are used where external systems need to push state back into the app.

Main entry points: [`src/lib/prisma.ts`](https://github.com/nishal77/localseobot/blob/main/src/lib/prisma.ts) (Prisma), [`src/app/dashboard/layout.tsx`](https://github.com/nishal77/localseobot/blob/main/src/app/dashboard/layout.tsx) (Dashboard shell), [`workers/index.ts`](https://github.com/nishal77/localseobot/blob/main/workers/index.ts) (Worker runtime), [`src/lib/queue.ts`](https://github.com/nishal77/localseobot/blob/main/src/lib/queue.ts) (Job queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>[layout.tsx]"]
  node_public_pages["Public pages<br/>landing/auth pages<br/>[page.tsx]"]
  node_dashboard_shell["Dashboard shell<br/>authenticated shell<br/>[layout.tsx]"]
  node_onboarding_page["Onboarding<br/>setup flow<br/>[page.tsx]"]
  node_ui_kit["UI kit<br/>design system<br/>[button.tsx]"]
  node_dash_widgets["Dashboard widgets<br/>page components<br/>[sidebar.tsx]"]
end

subgraph group_api["API"]
  node_auth_api["Auth API<br/>session boundary<br/>[route.ts]"]
  node_onboarding_api["Onboarding API<br/>setup api<br/>[route.ts]"]
  node_dashboard_api["Dashboard API<br/>metrics api<br/>[route.ts]"]
  node_citations_api["Citations API<br/>[route.ts]"]
  node_posts_api["Posts API<br/>content api<br/>[route.ts]"]
  node_rankings_api["Rankings API<br/>ranking api<br/>[route.ts]"]
  node_reports_api["Reports API<br/>reporting api<br/>[route.ts]"]
  node_reviews_api["Reviews API<br/>[route.ts]"]
  node_settings_api["Settings API<br/>account api<br/>[route.ts]"]
  node_webhooks_api["Webhooks<br/>external callbacks<br/>[route.ts]"]
end

subgraph group_core["Core services"]
  node_prisma[("Prisma<br/>data access<br/>[prisma.ts]")]
  node_queue["Job queue<br/>async dispatch<br/>[queue.ts]"]
  node_gbp["GBP client<br/>google business profile<br/>[gbp.ts]"]
  node_anthropic["AI client<br/>content generation<br/>[anthropic.ts]"]
  node_audit["Audit helpers<br/>onboarding checks<br/>[audit.ts]"]
  node_crypto["Crypto<br/>secret handling<br/>[crypto.ts]"]
end

subgraph group_workers["Workers"]
  node_worker_runtime["Worker runtime<br/>job runner<br/>[index.ts]"]
  node_scheduler["Scheduler<br/>[scheduler.ts]"]
  node_report_jobs["Report jobs<br/>report pipeline<br/>[report-generate.ts]"]
  node_review_jobs["Review jobs<br/>review pipeline<br/>[review-poll.ts]"]
  node_ranking_jobs["Ranking jobs<br/>tracking pipeline<br/>[ranking-check.ts]"]
  node_post_jobs["Post jobs<br/>content pipeline"]
  node_citation_jobs["Citation jobs<br/>citation pipeline"]
end

node_app_shell -->|"renders"| node_public_pages
node_app_shell -->|"wraps"| node_dashboard_shell
node_dashboard_shell -->|"uses"| node_dash_widgets
node_public_pages -->|"auth flow"| node_auth_api
node_onboarding_page -->|"submits"| node_onboarding_api
node_dashboard_shell -->|"loads"| node_dashboard_api
node_dashboard_shell -->|"loads"| node_citations_api
node_dashboard_shell -->|"loads"| node_posts_api
node_dashboard_shell -->|"loads"| node_rankings_api
node_dashboard_shell -->|"loads"| node_reports_api
node_dashboard_shell -->|"loads"| node_reviews_api
node_dashboard_shell -->|"loads"| node_settings_api
node_auth_api -->|"reads/writes"| node_prisma
node_auth_api -->|"secures"| node_crypto
node_onboarding_api -->|"reads/writes"| node_prisma
node_onboarding_api -->|"connects"| node_gbp
node_onboarding_api -->|"validates"| node_audit
node_onboarding_api -->|"enqueues"| node_queue
node_dashboard_api -->|"reads"| node_prisma
node_citations_api -->|"reads/writes"| node_prisma
node_citations_api -->|"enqueues"| node_queue
node_posts_api -->|"reads/writes"| node_prisma
node_posts_api -->|"enqueues"| node_queue
node_posts_api -->|"generates"| node_anthropic
node_posts_api -->|"publishes"| node_gbp
node_rankings_api -->|"reads/writes"| node_prisma
node_reports_api -->|"reads/writes"| node_prisma
node_reports_api -->|"enqueues"| node_queue
node_reports_api -->|"generates"| node_anthropic
node_reviews_api -->|"reads/writes"| node_prisma
node_reviews_api -->|"syncs"| node_gbp
node_reviews_api -->|"enqueues"| node_queue
node_settings_api -->|"reads/writes"| node_prisma
node_settings_api -->|"reconnects"| node_gbp
node_webhooks_api -->|"updates"| node_prisma
node_webhooks_api -->|"triggers"| node_queue
node_queue -->|"consumed by"| node_worker_runtime
node_scheduler -->|"starts"| node_worker_runtime
node_worker_runtime -->|"runs"| node_report_jobs
node_worker_runtime -->|"runs"| node_review_jobs
node_worker_runtime -->|"runs"| node_ranking_jobs
node_worker_runtime -->|"runs"| node_post_jobs
node_worker_runtime -->|"runs"| node_citation_jobs
node_report_jobs -->|"reads/writes"| node_prisma
node_report_jobs -->|"generates"| node_anthropic
node_review_jobs -->|"reads/writes"| node_prisma
node_review_jobs -->|"syncs"| node_gbp
node_ranking_jobs -->|"reads/writes"| node_prisma

click node_app_shell "https://github.com/nishal77/localseobot/blob/main/src/app/layout.tsx"
click node_public_pages "https://github.com/nishal77/localseobot/blob/main/src/app/page.tsx"
click node_dashboard_shell "https://github.com/nishal77/localseobot/blob/main/src/app/dashboard/layout.tsx"
click node_onboarding_page "https://github.com/nishal77/localseobot/blob/main/src/app/onboarding/page.tsx"
click node_ui_kit "https://github.com/nishal77/localseobot/blob/main/src/components/ui/button.tsx"
click node_dash_widgets "https://github.com/nishal77/localseobot/blob/main/src/components/dashboard/sidebar.tsx"
click node_auth_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_onboarding_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/onboarding/complete/route.ts"
click node_dashboard_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/dashboard/overview/route.ts"
click node_citations_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/citations/route.ts"
click node_posts_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/posts/route.ts"
click node_rankings_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/rankings/route.ts"
click node_reports_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/reports/route.ts"
click node_reviews_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/reviews/route.ts"
click node_settings_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/settings/route.ts"
click node_webhooks_api "https://github.com/nishal77/localseobot/blob/main/src/app/api/webhooks/whop/route.ts"
click node_prisma "https://github.com/nishal77/localseobot/blob/main/src/lib/prisma.ts"
click node_queue "https://github.com/nishal77/localseobot/blob/main/src/lib/queue.ts"
click node_gbp "https://github.com/nishal77/localseobot/blob/main/src/lib/gbp.ts"
click node_anthropic "https://github.com/nishal77/localseobot/blob/main/src/lib/anthropic.ts"
click node_audit "https://github.com/nishal77/localseobot/blob/main/src/lib/audit.ts"
click node_crypto "https://github.com/nishal77/localseobot/blob/main/src/lib/crypto.ts"
click node_worker_runtime "https://github.com/nishal77/localseobot/blob/main/workers/index.ts"
click node_scheduler "https://github.com/nishal77/localseobot/blob/main/workers/scheduler.ts"
click node_report_jobs "https://github.com/nishal77/localseobot/blob/main/workers/processors/report-generate.ts"
click node_review_jobs "https://github.com/nishal77/localseobot/blob/main/workers/processors/review-poll.ts"
click node_ranking_jobs "https://github.com/nishal77/localseobot/blob/main/workers/processors/ranking-check.ts"
click node_post_jobs "https://github.com/nishal77/localseobot/blob/main/workers/processors/gbp-post-generate.ts"
click node_citation_jobs "https://github.com/nishal77/localseobot/blob/main/workers/processors/citation-submit-batch.ts"

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_shell,node_public_pages,node_dashboard_shell,node_onboarding_page,node_ui_kit,node_dash_widgets toneBlue
class node_auth_api,node_onboarding_api,node_dashboard_api,node_citations_api,node_posts_api,node_rankings_api,node_reports_api,node_reviews_api,node_settings_api,node_webhooks_api toneAmber
class node_prisma,node_queue,node_gbp,node_anthropic,node_audit,node_crypto toneMint
class node_worker_runtime,node_scheduler,node_report_jobs,node_review_jobs,node_ranking_jobs,node_post_jobs,node_citation_jobs toneRose
```

## Components

### Frontend

Browser app, shared shell, and dashboard UI

- [App shell](https://github.com/nishal77/localseobot/blob/main/src/app/layout.tsx): next app shell · Root layout and global app chrome · `src/app/layout.tsx`
- [Public pages](https://github.com/nishal77/localseobot/blob/main/src/app/page.tsx): landing/auth pages · Homepage plus login and signup surfaces · `src/app/page.tsx`
- [Dashboard shell](https://github.com/nishal77/localseobot/blob/main/src/app/dashboard/layout.tsx): authenticated shell · Protected dashboard layout and navigation · `src/app/dashboard/layout.tsx`
- [Onboarding](https://github.com/nishal77/localseobot/blob/main/src/app/onboarding/page.tsx): setup flow · User onboarding entry point · `src/app/onboarding/page.tsx`
- [UI kit](https://github.com/nishal77/localseobot/blob/main/src/components/ui/button.tsx): design system · Reusable primitives for forms and layout · `src/components/ui/button.tsx`
- [Dashboard widgets](https://github.com/nishal77/localseobot/blob/main/src/components/dashboard/sidebar.tsx): page components · Custom dashboard controls and sidebar · `src/components/dashboard/sidebar.tsx`

### API

Route handlers organized by product domain

- [Auth API](https://github.com/nishal77/localseobot/blob/main/src/app/api/auth/[...nextauth]/route.ts): session boundary · NextAuth session and signup endpoints · `src/app/api/auth/[...nextauth]/route.ts`
- [Onboarding API](https://github.com/nishal77/localseobot/blob/main/src/app/api/onboarding/complete/route.ts): setup api · Business setup, GBP connect, and completion routes · `src/app/api/onboarding/complete/route.ts`
- [Dashboard API](https://github.com/nishal77/localseobot/blob/main/src/app/api/dashboard/overview/route.ts): metrics api · Overview and activity data for the dashboard · `src/app/api/dashboard/overview/route.ts`
- [Citations API](https://github.com/nishal77/localseobot/blob/main/src/app/api/citations/route.ts): citations api · Citation inventory, stats, and retry flows · `src/app/api/citations/route.ts`
- [Posts API](https://github.com/nishal77/localseobot/blob/main/src/app/api/posts/route.ts): content api · Post listing, approval, and status routes · `src/app/api/posts/route.ts`
- [Rankings API](https://github.com/nishal77/localseobot/blob/main/src/app/api/rankings/route.ts): ranking api · Keyword tracking and history routes · `src/app/api/rankings/route.ts`
- [Reports API](https://github.com/nishal77/localseobot/blob/main/src/app/api/reports/route.ts): reporting api · Report generation and retrieval routes · `src/app/api/reports/route.ts`
- [Reviews API](https://github.com/nishal77/localseobot/blob/main/src/app/api/reviews/route.ts): reviews api · Review polling, approval, and response routes · `src/app/api/reviews/route.ts`
- [Settings API](https://github.com/nishal77/localseobot/blob/main/src/app/api/settings/route.ts): account api · Business, GBP, bot, and billing settings surface · `src/app/api/settings/route.ts`
- [Webhooks](https://github.com/nishal77/localseobot/blob/main/src/app/api/webhooks/whop/route.ts): external callbacks · Inbound events from billing and content workflows · `src/app/api/webhooks/whop/route.ts`

### Core services

Shared runtime libraries and persistence

- [Prisma](https://github.com/nishal77/localseobot/blob/main/src/lib/prisma.ts): data access · Database gateway and shared models · `src/lib/prisma.ts`
- [Job queue](https://github.com/nishal77/localseobot/blob/main/src/lib/queue.ts): async dispatch · Shared queue boundary between routes and workers · `src/lib/queue.ts`
- [GBP client](https://github.com/nishal77/localseobot/blob/main/src/lib/gbp.ts): google business profile · Integration for business profile operations · `src/lib/gbp.ts`
- [AI client](https://github.com/nishal77/localseobot/blob/main/src/lib/anthropic.ts): content generation · Anthropic-powered drafting and generation · `src/lib/anthropic.ts`
- [Audit helpers](https://github.com/nishal77/localseobot/blob/main/src/lib/audit.ts): onboarding checks · Onboarding and account state validation · `src/lib/audit.ts`
- [Crypto](https://github.com/nishal77/localseobot/blob/main/src/lib/crypto.ts): secret handling · Sensitive token and credential utilities · `src/lib/crypto.ts`

### Workers

Background execution and scheduled jobs

- [Worker runtime](https://github.com/nishal77/localseobot/blob/main/workers/index.ts): job runner · Background worker entrypoint and processor wiring · `workers/index.ts`
- [Scheduler](https://github.com/nishal77/localseobot/blob/main/workers/scheduler.ts): job scheduler · Timed triggers for recurring background work · `workers/scheduler.ts`
- [Report jobs](https://github.com/nishal77/localseobot/blob/main/workers/processors/report-generate.ts): report pipeline · Generate and send reports in the background · `workers/processors/report-generate.ts`
- [Review jobs](https://github.com/nishal77/localseobot/blob/main/workers/processors/review-poll.ts): review pipeline · Poll, draft, and respond to reviews · `workers/processors/review-poll.ts`
- [Ranking jobs](https://github.com/nishal77/localseobot/blob/main/workers/processors/ranking-check.ts): tracking pipeline · Keyword and competitor monitoring jobs · `workers/processors/ranking-check.ts`
- [Post jobs](https://github.com/nishal77/localseobot/blob/main/workers/processors/gbp-post-generate.ts): content pipeline · Generate and publish GBP posts · `workers/processors/gbp-post-generate.ts`
- [Citation jobs](https://github.com/nishal77/localseobot/blob/main/workers/processors/citation-submit-batch.ts): citation pipeline · Batch citation submission and retry work · `workers/processors/citation-submit-batch.ts`

## Connections

- App shell → Public pages: renders · Root shell frames public routes
- App shell → Dashboard shell: wraps · Root shell contains the authenticated area
- Dashboard shell → Dashboard widgets: uses · Dashboard layout composes reusable controls
- Public pages → Auth API: auth flow · Login and signup rely on session endpoints
- Onboarding → Onboarding API: submits · Setup flow posts business and GBP data
- Dashboard shell → Dashboard API: loads · Dashboard screens read overview and activity data
- Dashboard shell → Citations API: loads · Citations page reads citation state
- Dashboard shell → Posts API: loads · Posts page reads and approves content
- Dashboard shell → Rankings API: loads · Rankings page reads tracking data
- Dashboard shell → Reports API: loads · Reports page reads generated reports
- Dashboard shell → Reviews API: loads · Reviews page reads review state and drafts
- Dashboard shell → Settings API: loads · Settings pages manage account and integration state
- Auth API → Prisma: reads/writes · Session and signup state is persisted
- Auth API → Crypto: secures · Credential handling uses shared crypto utilities
- Onboarding API → Prisma: reads/writes · Stores business and onboarding progress
- Onboarding API → GBP client: connects · Starts and completes GBP linkage
- Onboarding API → Audit helpers: validates · Runs onboarding checks and audit results
- Onboarding API → Job queue: enqueues · Can trigger downstream async setup work
- Dashboard API → Prisma: reads · Aggregates product state from the database
- Citations API → Prisma: reads/writes · Tracks citation records and retry status
- Citations API → Job queue: enqueues · Schedules citation submission jobs
- Posts API → Prisma: reads/writes · Persists posts and approval state
- Posts API → Job queue: enqueues · Sends post work to background processing
- Posts API → AI client: generates · Uses AI for drafting and content assistance
- Posts API → GBP client: publishes · Posts are sent to Google Business Profile
- Rankings API → Prisma: reads/writes · Stores keyword tracking and history
- Reports API → Prisma: reads/writes · Persists report results and snapshots
- Reports API → Job queue: enqueues · Report generation is dispatched asynchronously
- Reports API → AI client: generates · AI may assist with report drafting
- Reviews API → Prisma: reads/writes · Stores reviews, approvals, and responses
- Reviews API → GBP client: syncs · Talks to GBP for review operations
- Reviews API → Job queue: enqueues · Review response work can be deferred
- Settings API → Prisma: reads/writes · Persists business, bot, and billing settings
- Settings API → GBP client: reconnects · Manages GBP reconnect and profile settings
- Webhooks → Prisma: updates · External events update internal account state
- Webhooks → Job queue: triggers · Webhook events may kick off background work
- Job queue → Worker runtime: consumed by · Queued jobs are picked up by workers
- Scheduler → Worker runtime: starts · Scheduler feeds the worker process
- Worker runtime → Report jobs: runs · Worker executes report generation jobs
- Worker runtime → Review jobs: runs · Worker executes review polling and response jobs
- Worker runtime → Ranking jobs: runs · Worker executes ranking and competitor checks
- Worker runtime → Post jobs: runs · Worker executes GBP content jobs
- Worker runtime → Citation jobs: runs · Worker executes citation submission jobs
- Report jobs → Prisma: reads/writes · Reports are assembled from stored domain data
- Report jobs → AI client: generates · Report content can be AI-assisted
- Review jobs → Prisma: reads/writes · Review processing updates stored records
- Review jobs → GBP client: syncs · Polls and responds through GBP
- Ranking jobs → Prisma: reads/writes · Ranking snapshots and history are persisted