How ranjeetj06/seo-frontend works
1. This repository is a React 19 + TypeScript single-page frontend for an “AI SEO Platform.” Its job is to present SEO, AI visibility, keyword, crawler, analytics, and outreach workflows while delegating almost all business logic to a FastAPI backend at /api/v1.
2. The app is built with Vite and deployed to Vercel. Styling is handled with Tailwind CSS, routing with React Router 7, and global client state is managed with Zustand. The architectural boundary is clear: the frontend is a thin orchestration/UI layer, not a processing engine.
3. Routing is centered in src/App.tsx with page-level screens under src/pages. The main user areas are dashboard, analysis tools, reports, crawler, competitor analysis, AI tools, settings, onboarding, login, and OAuth callback pages. src/routes/ProtectedRoute.tsx is the access boundary that keeps authenticated-only pages separate from public entry points like login/landing.
4. Shared UI is organized into reusable layout and presentation components in src/components, including Layout, Sidebar, SubNav, Card, Field, StatCard, and chart widgets. This indicates a consistent shell around the app content, with pages focusing on data and workflows rather than navigation chrome.
5. Backend communication is centralized in src/api/client.ts and split by domain in src/api/*.ts (auth, seo, ai, outreach, analytics, projects, organizations, keywords, crawler, searchConsole). This separation maps directly to backend resource boundaries and is the clearest place to draw service-level interfaces in an architecture diagram.
6. Authentication is JWT-based. The login page exchanges credentials for a token, Zustand auth state stores the session, and the Axios client injects auth headers on every request. This creates a simple one-way dependency: UI → auth store/API client → backend.
7. A major architectural feature is async task handling. Several backend endpoints enqueue work and return 202 with a task_id; the frontend then polls GET /tasks/{id} until success or failure. The reusable useTaskPolling hook drives this for SEO screens, while src/api/ai.ts hides the polling inside submit-and-poll helpers so AI-tool screens can behave like normal request/response flows.
8. The SEO analysis subsystem is centered on pages such as Analyze Website, Tech Audit, AI Visibility, Keywords, Competitor, Reports, and Crawler. These screens appear to cover site evaluation, technical audits, AI/GEO/AEO visibility, keyword extraction/clustering, competitor comparison, and crawl/sitemap inspection, all backed by domain-specific API modules and task polling.
9. The AI Tools subsystem is separate from core SEO analysis. It includes recommendation, backlink-building, outbound prospecting, and RAG-related workflows. The design implies a workflow engine style UI: submit a job, wait for task completion, then review generated outputs rather than requiring continuous user interaction.
10. Outreach is a distinct end-to-end module under src/components/outreach and src/pages/Settings / AI Tools. The user flow connects Gmail via OAuth, manages email accounts, templates, campaigns, and a dashboard for sent activity. This is a second major boundary in the app: authenticated SEO analysis on one side, connected outbound email operations on the other.
11. OAuth is handled through dedicated callback routes, including Google and Search Console callbacks. That suggests the frontend participates in multiple external integrations: Google for Gmail/email sending, and Search Console for analytics data access. These are entry/return points rather than business logic endpoints.
12. Organization and project context are modeled explicitly via stores and UI elements like OrgSwitcher and OrganizationPanel, plus src/store/org.ts and src/store/projects.ts. This means the app is multi-tenant or at least scoped by organization/project, and many views likely depend on a selected org/project context for API queries.
13. The architecture is therefore best drawn as: public routes and auth → protected SPA shell → page-level feature modules → shared API client → backend domain services → async task queue/worker for long-running jobs → external services such as Google OAuth/Search Console/Gmail. The key design pattern is a thin, composable frontend with centralized network, auth, and polling boundaries.
Main entry points: Sidebar.tsx Sidebar · index.ts Domain APIs · Layout.tsx Layout · client.ts API Client
Components 22
Public entry
Unauthenticated routes and return points from external OAuth flows.
- Landing · Marketing or unauthenticated entry page.
src/pages/Landing.tsx - Login · Credential sign-in and JWT bootstrap.
src/pages/Login.tsx - Google OAuth · Return route for Google-based integrations.
src/pages/OAuthGoogleCallback.tsx - Search Console · Return route for Search Console authorization.
src/pages/OAuthSearchConsoleCallback.tsx - Analytics OAuth · Return route for analytics authorization.
src/pages/OAuthAnalyticsCallback.tsx
SPA shell
Shared layout, navigation, and route protection for authenticated app areas.
- Protected Route · Access boundary for authenticated pages.
src/routes/ProtectedRoute.tsx - Layout · Primary authenticated page shell.
src/components/Layout.tsx - Sidebar · Main navigation and section switching.
src/components/Sidebar.tsx - SubNav · Secondary navigation within feature areas.
src/components/SubNav.tsx
Feature pages
Page-level SEO, AI, analytics, and outreach workflows.
- Dashboard · Authenticated landing and summary view.
src/pages/Dashboard.tsx - SEO Suite · Core site analysis, audits, keywords, competitors, reports, crawler, and visibility workflows.
- AI Tools · Recommendation, backlink, outreach, and RAG-style job flows.
src/pages/AITools.tsx - Analytics · Analytics-facing reporting and insights.
src/pages/Analytics.tsx - Outreach · Campaigns, templates, accounts, and sent-activity dashboard.
src/components/outreach/OutreachDashboard.tsx
Client data
Centralized API access, auth state, org/project context, and task polling.
- Org Context · Selected organization and project scope used across the app.
src/store/org.ts - Auth Store · JWT session and logged-in user state.
src/store/auth.ts - API Client · Shared Axios client with auth header injection and backend base handling.
src/api/client.ts - Domain APIs · Feature-aligned API modules for auth, SEO, AI, outreach, analytics, projects, organizations, keywords, crawler, and Search Console.
src/api/index.ts - Task Polling · Reusable polling for long-running backend jobs and 202 responses.
src/hooks/useTaskPolling.ts
External services
Backend API, async workers, and third-party services reached through the frontend.
- FastAPI Backend · Primary backend at /api/v1.
- Task Queue · Async processing for long-running SEO and AI jobs.
- Google Services · Google OAuth, Gmail/email sending, and Search Console access.
Connections 29
- Landing → Protected Route: enter app · Public users move into authenticated areas after sign-in.
- Login → Auth Store: store session · Successful login persists JWT/session state.
- Login → API Client: authenticate · Credentials are exchanged through the shared HTTP client.
- Google OAuth → Google Services: complete OAuth · Google callback returns from external authorization.
- Search Console → Google Services: complete OAuth · Search Console callback returns from Google authorization.
- Analytics OAuth → FastAPI Backend: complete OAuth · Analytics callback finalizes integration on the backend.
- Protected Route → Layout: render shell · Authenticated routes render inside the shared layout.
- Layout → Sidebar: compose · Layout includes global navigation.
- Layout → SubNav: compose · Layout includes context-sensitive secondary navigation.
- Layout → Org Context: scope views · Shell reacts to selected organization/project context.
- Sidebar → Dashboard: navigate · Primary navigation reaches the dashboard.
- Sidebar → SEO Suite: navigate · Navigation links to SEO analysis sections.
- Sidebar → AI Tools: navigate · Navigation links to AI workflows.
- Sidebar → Analytics: navigate · Navigation links to analytics views.
- Sidebar → Outreach: navigate · Navigation links to outreach operations.
- Dashboard → API Client: load data · Overview data comes from backend services.
- SEO Suite → Domain APIs: query domains · SEO pages use domain-specific API modules.
- SEO Suite → Task Polling: poll jobs · Long-running analysis uses reusable polling.
- AI Tools → Domain APIs: submit jobs · AI workflows call dedicated API helpers.
- AI Tools → Task Queue: wait for result · Backend work is handled asynchronously.
- Analytics → Domain APIs: fetch reports · Analytics data is loaded through service modules.
- Outreach → Domain APIs: manage campaigns · Outreach screens call outreach and auth endpoints.
- Org Context → Domain APIs: scope requests · Organization and project selection shape API calls.
- Auth Store → API Client: inject auth · Stored JWT is attached to outgoing requests.
- API Client → FastAPI Backend: request API · All frontend data access is centralized through the backend API.
- Domain APIs → FastAPI Backend: resource calls · Feature modules map to backend domain boundaries.
- Task Polling → FastAPI Backend: check status · Polling reads task state from the backend.
- FastAPI Backend → Task Queue: enqueue work · Long-running jobs are handed to workers and polled later.
- FastAPI Backend → Google Services: integrate · Backend exchanges tokens and accesses Google services.