# nagarajumedi/open-seo architecture

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

- Interactive diagram: https://gitdiagram.com/nagarajumedi/open-seo
- Repository: https://github.com/nagarajumedi/open-seo

## Overview

OpenSEO is a self-hostable, pay-as-you-go SEO research suite with hosted accounts and project workspaces. Users select a project and run focused workflows—keyword and domain research, rank tracking, backlinks, audits, AI visibility, and search-performance analysis—then inspect results and manage integrations. The README also highlights MCP and agent skills as a way to use SEO data through AI agents. The tree and excerpts establish the main product areas, but do not show most server-function wiring, so uncertain call and persistence links are omitted.

Main entry points: [`src/routes/_app/route.tsx`](https://github.com/nagarajumedi/open-seo/blob/main/src/routes/_app/route.tsx) (App routes), [`src/routes/_project/p/$projectId/route.tsx`](https://github.com/nagarajumedi/open-seo/blob/main/src/routes/_project/p/%24projectId/route.tsx) (Project workspace), [`src/client/features/keywords/page/KeywordResearchPage.tsx`](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/keywords/page/KeywordResearchPage.tsx) (Keyword research), [`src/server/features/keywords/services/KeywordResearchService.ts`](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/keywords/services/KeywordResearchService.ts) (Keyword research service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and access"]
  node_app["App routes<br/>[route.tsx]"]
  node_project["Project workspace<br/>[route.tsx]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_project_context["Project context"]
end

subgraph group_research["SEO research"]
  node_keywords_ui["Keyword research"]
  node_keywords_service["Keyword research service"]
  node_domain_ui["Domain insights"]
  node_domain_service["Domain service<br/>[DomainService.ts]"]
  node_rank_tracking["Rank tracking"]
  node_backlinks_ui["Backlink analysis<br/>[BacklinksPage.tsx]"]
  node_backlinks_service["Backlink service"]
  node_audit_ui["Site audits<br/>[LaunchView.tsx]"]
  node_audit_service["Audit service<br/>[AuditService.ts]"]
end

subgraph group_insights["Measurement and AI"]
  node_ai_search_ui["AI visibility"]
  node_ai_search_service["AI search services<br/>[brandLookup.ts]"]
  node_search_performance["Search performance"]
  node_google_services["Google integrations<br/>[Ga4Service.ts]"]
end

subgraph group_platform["Services and integrations"]
  node_mcp["MCP and agent access<br/>[mcpActivation.ts]"]
  node_db_provider["Database provider<br/>[provider.ts]"]
  node_database[("Application data<br/>[schema.ts]")]
end

node_person(("SEO user"))
node_dataforseo["DataForSEO"]
node_google["Google services"]
node_agent(("AI agent"))

node_person -->|"opens"| node_app
node_app -->|"authenticates"| node_auth
node_person -->|"selects project"| node_project
node_project -->|"configures"| node_project_context
node_person -->|"researches keywords"| node_keywords_ui
node_person -->|"explores domain"| node_domain_ui
node_person -->|"tracks rankings"| node_rank_tracking
node_person -->|"reviews backlinks"| node_backlinks_ui
node_person -->|"starts audit"| node_audit_ui
node_person -->|"checks visibility"| node_ai_search_ui
node_person -->|"reviews performance"| node_search_performance
node_agent -->|"uses SEO data"| node_mcp
node_keywords_ui --> node_keywords_service
node_domain_ui --> node_domain_service
node_backlinks_ui --> node_backlinks_service
node_audit_ui -->|"starts audit"| node_audit_service
node_ai_search_ui --> node_ai_search_service
node_search_performance --> node_google_services
node_keywords_service --> node_dataforseo
node_domain_service --> node_dataforseo
node_backlinks_service --> node_dataforseo
node_db_provider --> node_database
node_google_services --> node_google

click node_app "https://github.com/nagarajumedi/open-seo/blob/main/src/routes/_app/route.tsx"
click node_project "https://github.com/nagarajumedi/open-seo/blob/main/src/routes/_project/p/%24projectId/route.tsx"
click node_auth "https://github.com/nagarajumedi/open-seo/blob/main/src/lib/auth.ts"
click node_project_context "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/project-context/services/ProjectContextService.ts"
click node_keywords_ui "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/keywords/page/KeywordResearchPage.tsx"
click node_keywords_service "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/keywords/services/KeywordResearchService.ts"
click node_domain_ui "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/domain/DomainOverviewPage.tsx"
click node_domain_service "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/domain/services/DomainService.ts"
click node_rank_tracking "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/rank-tracking/RankTrackingOverview.tsx"
click node_backlinks_ui "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/backlinks/BacklinksPage.tsx"
click node_backlinks_service "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/backlinks/services/BacklinksService.ts"
click node_audit_ui "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/audit/launch/LaunchView.tsx"
click node_audit_service "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/audit/services/AuditService.ts"
click node_ai_search_ui "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/ai-search/BrandLookupPage.tsx"
click node_ai_search_service "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/ai-search/services/brandLookup.ts"
click node_search_performance "https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/search-performance/SearchPerformancePage.tsx"
click node_google_services "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/ga4/services/Ga4Service.ts"
click node_mcp "https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/activation/mcpActivation.ts"
click node_db_provider "https://github.com/nagarajumedi/open-seo/blob/main/src/db/provider.ts"
click node_database "https://github.com/nagarajumedi/open-seo/blob/main/src/db/schema.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,node_project,node_auth,node_project_context,node_person toneBlue
class node_keywords_ui,node_keywords_service,node_domain_ui,node_domain_service,node_rank_tracking,node_backlinks_ui,node_backlinks_service,node_audit_ui,node_audit_service toneAmber
class node_ai_search_ui,node_ai_search_service,node_search_performance,node_google_services toneMint
class node_mcp,node_db_provider,node_database toneRose
class node_dataforseo,node_google,node_agent toneIndigo
```

## Components

### Workspace and access

- [App routes](https://github.com/nagarajumedi/open-seo/blob/main/src/routes/_app/route.tsx): `src/routes/_app/route.tsx`
- [Project workspace](https://github.com/nagarajumedi/open-seo/blob/main/src/routes/_project/p/%24projectId/route.tsx): `src/routes/_project/p/$projectId/route.tsx`
- [Authentication](https://github.com/nagarajumedi/open-seo/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Project context](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/project-context/services/ProjectContextService.ts): `src/server/features/project-context/services/ProjectContextService.ts`

### SEO research

- [Keyword research](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/keywords/page/KeywordResearchPage.tsx): `src/client/features/keywords/page/KeywordResearchPage.tsx`
- [Keyword research service](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/keywords/services/KeywordResearchService.ts): `src/server/features/keywords/services/KeywordResearchService.ts`
- [Domain insights](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/domain/DomainOverviewPage.tsx): `src/client/features/domain/DomainOverviewPage.tsx`
- [Domain service](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/domain/services/DomainService.ts): `src/server/features/domain/services/DomainService.ts`
- [Rank tracking](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/rank-tracking/RankTrackingOverview.tsx): `src/client/features/rank-tracking/RankTrackingOverview.tsx`
- [Backlink analysis](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/backlinks/BacklinksPage.tsx): `src/client/features/backlinks/BacklinksPage.tsx`
- [Backlink service](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/backlinks/services/BacklinksService.ts): `src/server/features/backlinks/services/BacklinksService.ts`
- [Site audits](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/audit/launch/LaunchView.tsx): `src/client/features/audit/launch/LaunchView.tsx`
- [Audit service](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/audit/services/AuditService.ts): `src/server/features/audit/services/AuditService.ts`

### Measurement and AI

- [AI visibility](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/ai-search/BrandLookupPage.tsx): `src/client/features/ai-search/BrandLookupPage.tsx`
- [AI search services](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/ai-search/services/brandLookup.ts): `src/server/features/ai-search/services/brandLookup.ts`
- [Search performance](https://github.com/nagarajumedi/open-seo/blob/main/src/client/features/search-performance/SearchPerformancePage.tsx): `src/client/features/search-performance/SearchPerformancePage.tsx`
- [Google integrations](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/ga4/services/Ga4Service.ts): `src/server/features/ga4/services/Ga4Service.ts`

### Services and integrations

- [MCP and agent access](https://github.com/nagarajumedi/open-seo/blob/main/src/server/features/activation/mcpActivation.ts): `src/server/features/activation/mcpActivation.ts`
- [Database provider](https://github.com/nagarajumedi/open-seo/blob/main/src/db/provider.ts): `src/db/provider.ts`
- [Application data](https://github.com/nagarajumedi/open-seo/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Other components

- **SEO user**
- **DataForSEO**
- **Google services**
- **AI agent**

## Connections

- SEO user → App routes: opens
- App routes → Authentication: authenticates
- SEO user → Project workspace: selects project
- Project workspace → Project context: configures
- SEO user → Keyword research: researches keywords
- SEO user → Domain insights: explores domain
- SEO user → Rank tracking: tracks rankings
- SEO user → Backlink analysis: reviews backlinks
- SEO user → Site audits: starts audit
- SEO user → AI visibility: checks visibility
- SEO user → Search performance: reviews performance
- AI agent → MCP and agent access: uses SEO data
- Keyword research → Keyword research service
- Domain insights → Domain service
- Backlink analysis → Backlink service
- Site audits → Audit service: starts audit
- AI visibility → AI search services
- Search performance → Google integrations
- Keyword research service → DataForSEO
- Domain service → DataForSEO
- Backlink service → DataForSEO
- Database provider → Application data
- Google integrations → Google services