# ranjeetj06/seo-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/ranjeetj06/seo-frontend
- Repository: https://github.com/ranjeetj06/seo-frontend

## Overview

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: [`src/components/Sidebar.tsx`](https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/Sidebar.tsx) (Sidebar), [`src/api/index.ts`](https://github.com/ranjeetj06/seo-frontend/blob/master/src/api/index.ts) (Domain APIs), [`src/components/Layout.tsx`](https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/Layout.tsx) (Layout), [`src/api/client.ts`](https://github.com/ranjeetj06/seo-frontend/blob/master/src/api/client.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public entry"]
  node_landing["Landing<br/>public page<br/>[Landing.tsx]"]
  node_login["Login<br/>auth page<br/>[Login.tsx]"]
  node_oauth_google["Google OAuth<br/>callback page"]
  node_oauth_searchconsole["Search Console<br/>callback page"]
  node_oauth_analytics["Analytics OAuth<br/>callback page"]
end

subgraph group_shell["SPA shell"]
  node_protected_route{{"Protected Route<br/>route guard<br/>[ProtectedRoute.tsx]"}}
  node_layout["Layout<br/>app shell<br/>[Layout.tsx]"]
  node_sidebar["Sidebar<br/>nav shell<br/>[Sidebar.tsx]"]
  node_subnav["SubNav<br/>context nav<br/>[SubNav.tsx]"]
end

subgraph group_features["Feature pages"]
  node_dashboard["Dashboard<br/>overview page<br/>[Dashboard.tsx]"]
  node_seo_suite["SEO Suite<br/>analysis pages"]
  node_ai_tools["AI Tools<br/>workflow pages<br/>[AITools.tsx]"]
  node_analytics["Analytics<br/>reporting page<br/>[Analytics.tsx]"]
  node_outreach["Outreach<br/>email ops"]
end

subgraph group_data["Client data"]
  node_org_context[("Org Context<br/>tenant state<br/>[org.ts]")]
  node_auth_store[("Auth Store<br/>session state<br/>[auth.ts]")]
  node_api_client["API Client<br/>http core<br/>[client.ts]"]
  node_domain_apis["Domain APIs<br/>service modules<br/>[index.ts]"]
  node_task_polling["Task Polling<br/>async hook<br/>[useTaskPolling.ts]"]
end

subgraph group_integrations["External services"]
  node_backend_api[("FastAPI Backend<br/>server api")]
  node_task_queue["Task Queue<br/>worker jobs"]
  node_google_services(("Google Services<br/>oauth/data providers"))
end

node_landing -->|"enter app"| node_protected_route
node_login -->|"store session"| node_auth_store
node_login -->|"authenticate"| node_api_client
node_oauth_google -->|"complete OAuth"| node_google_services
node_oauth_searchconsole -->|"complete OAuth"| node_google_services
node_oauth_analytics -->|"complete OAuth"| node_backend_api
node_protected_route -->|"render shell"| node_layout
node_layout -->|"compose"| node_sidebar
node_layout -->|"compose"| node_subnav
node_layout -->|"scope views"| node_org_context
node_sidebar -->|"navigate"| node_dashboard
node_sidebar -->|"navigate"| node_seo_suite
node_sidebar -->|"navigate"| node_ai_tools
node_sidebar -->|"navigate"| node_analytics
node_sidebar -->|"navigate"| node_outreach
node_dashboard -->|"load data"| node_api_client
node_seo_suite -->|"query domains"| node_domain_apis
node_seo_suite -->|"poll jobs"| node_task_polling
node_ai_tools -->|"submit jobs"| node_domain_apis
node_ai_tools -->|"wait for result"| node_task_queue
node_analytics -->|"fetch reports"| node_domain_apis
node_outreach -->|"manage campaigns"| node_domain_apis
node_org_context -->|"scope requests"| node_domain_apis
node_auth_store -->|"inject auth"| node_api_client
node_api_client -->|"request API"| node_backend_api
node_domain_apis -->|"resource calls"| node_backend_api
node_task_polling -->|"check status"| node_backend_api
node_backend_api -->|"enqueue work"| node_task_queue
node_backend_api -->|"integrate"| node_google_services

click node_landing "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Landing.tsx"
click node_login "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Login.tsx"
click node_oauth_google "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/OAuthGoogleCallback.tsx"
click node_oauth_searchconsole "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/OAuthSearchConsoleCallback.tsx"
click node_oauth_analytics "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/OAuthAnalyticsCallback.tsx"
click node_protected_route "https://github.com/ranjeetj06/seo-frontend/blob/master/src/routes/ProtectedRoute.tsx"
click node_layout "https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/Layout.tsx"
click node_sidebar "https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/Sidebar.tsx"
click node_subnav "https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/SubNav.tsx"
click node_dashboard "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Dashboard.tsx"
click node_ai_tools "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/AITools.tsx"
click node_analytics "https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Analytics.tsx"
click node_outreach "https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/outreach/OutreachDashboard.tsx"
click node_org_context "https://github.com/ranjeetj06/seo-frontend/blob/master/src/store/org.ts"
click node_auth_store "https://github.com/ranjeetj06/seo-frontend/blob/master/src/store/auth.ts"
click node_api_client "https://github.com/ranjeetj06/seo-frontend/blob/master/src/api/client.ts"
click node_domain_apis "https://github.com/ranjeetj06/seo-frontend/blob/master/src/api/index.ts"
click node_task_polling "https://github.com/ranjeetj06/seo-frontend/blob/master/src/hooks/useTaskPolling.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_landing,node_login,node_oauth_google,node_oauth_searchconsole,node_oauth_analytics toneBlue
class node_protected_route,node_layout,node_sidebar,node_subnav toneAmber
class node_dashboard,node_seo_suite,node_ai_tools,node_analytics,node_outreach toneMint
class node_org_context,node_auth_store,node_api_client,node_domain_apis,node_task_polling toneRose
class node_backend_api,node_task_queue,node_google_services toneIndigo
```

## Components

### Public entry

Unauthenticated routes and return points from external OAuth flows.

- [Landing](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Landing.tsx): public page · Marketing or unauthenticated entry page. · `src/pages/Landing.tsx`
- [Login](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Login.tsx): auth page · Credential sign-in and JWT bootstrap. · `src/pages/Login.tsx`
- [Google OAuth](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/OAuthGoogleCallback.tsx): callback page · Return route for Google-based integrations. · `src/pages/OAuthGoogleCallback.tsx`
- [Search Console](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/OAuthSearchConsoleCallback.tsx): callback page · Return route for Search Console authorization. · `src/pages/OAuthSearchConsoleCallback.tsx`
- [Analytics OAuth](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/OAuthAnalyticsCallback.tsx): callback page · Return route for analytics authorization. · `src/pages/OAuthAnalyticsCallback.tsx`

### SPA shell

Shared layout, navigation, and route protection for authenticated app areas.

- [Protected Route](https://github.com/ranjeetj06/seo-frontend/blob/master/src/routes/ProtectedRoute.tsx): route guard · Access boundary for authenticated pages. · `src/routes/ProtectedRoute.tsx`
- [Layout](https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/Layout.tsx): app shell · Primary authenticated page shell. · `src/components/Layout.tsx`
- [Sidebar](https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/Sidebar.tsx): nav shell · Main navigation and section switching. · `src/components/Sidebar.tsx`
- [SubNav](https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/SubNav.tsx): context nav · Secondary navigation within feature areas. · `src/components/SubNav.tsx`

### Feature pages

Page-level SEO, AI, analytics, and outreach workflows.

- [Dashboard](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Dashboard.tsx): overview page · Authenticated landing and summary view. · `src/pages/Dashboard.tsx`
- **SEO Suite**: analysis pages · Core site analysis, audits, keywords, competitors, reports, crawler, and visibility workflows.
- [AI Tools](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/AITools.tsx): workflow pages · Recommendation, backlink, outreach, and RAG-style job flows. · `src/pages/AITools.tsx`
- [Analytics](https://github.com/ranjeetj06/seo-frontend/blob/master/src/pages/Analytics.tsx): reporting page · Analytics-facing reporting and insights. · `src/pages/Analytics.tsx`
- [Outreach](https://github.com/ranjeetj06/seo-frontend/blob/master/src/components/outreach/OutreachDashboard.tsx): email ops · 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](https://github.com/ranjeetj06/seo-frontend/blob/master/src/store/org.ts): tenant state · Selected organization and project scope used across the app. · `src/store/org.ts`
- [Auth Store](https://github.com/ranjeetj06/seo-frontend/blob/master/src/store/auth.ts): session state · JWT session and logged-in user state. · `src/store/auth.ts`
- [API Client](https://github.com/ranjeetj06/seo-frontend/blob/master/src/api/client.ts): http core · Shared Axios client with auth header injection and backend base handling. · `src/api/client.ts`
- [Domain APIs](https://github.com/ranjeetj06/seo-frontend/blob/master/src/api/index.ts): service modules · Feature-aligned API modules for auth, SEO, AI, outreach, analytics, projects, organizations, keywords, crawler, and Search Console. · `src/api/index.ts`
- [Task Polling](https://github.com/ranjeetj06/seo-frontend/blob/master/src/hooks/useTaskPolling.ts): async hook · 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**: server api · Primary backend at /api/v1.
- **Task Queue**: worker jobs · Async processing for long-running SEO and AI jobs.
- **Google Services**: oauth/data providers · Google OAuth, Gmail/email sending, and Search Console access.

## Connections

- 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.
