nishal77/localseobot

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.