How React Components Are Organized in the Open-SEO `src` Directory

Open-SEO structures its React components using a feature-driven architecture with three main areas: src/routes for page-level components, src/client for UI and feature modules, and src/shared for pure logic utilities.

This organization pattern, as implemented in the every-app/open-seo repository, separates routing concerns from presentation logic while keeping related feature code colocated. The result is a codebase where developers can quickly locate components by their functional domain.

The Three-Layer src Architecture

The top-level src directory follows a clear separation of concerns:

Area	Purpose	Typical Contents
src/routes	Page-level route components generated by the Remix-style router	verify-email.tsx, reset-password.tsx, _app/index.tsx, _project/p/$projectId/...
src/client	UI components grouped by functional domain, including layouts and feature modules	layout/AppShell.tsx, components/Sidebar.tsx, features/search-performance/*
src/shared	Pure-logic helpers with no JSX—types, utilities, and API wrappers	keyword-locations.ts, ga4.ts, billing.ts

This structure ensures that route files remain thin, delegating complex UI to feature components while shared utilities can be imported anywhere without creating circular dependencies.

Feature-Based Organization in src/client/features

The heart of Open-SEO's component organization lives in src/client/features/. Each major product capability gets its own subfolder containing page components, tables, charts, and supporting UI.

Search Performance

The Search Performance feature handles the analytics dashboard for Google Search Console data. It includes table views, loading states, and chart configurations.

• SearchPerformancePage.tsx — Main page container
• SearchPerformanceParts.tsx — Composable subcomponents
• SearchPerformanceColumns.tsx — Table column definitions

Source: [src/client/features/search-performance/SearchPerformancePage.tsx](https://github.com/every-app/open-seo/blob/main/src/client/features/search-performance/SearchPerformancePage.tsx)

Backlinks

The Backlinks feature provides a complete backlink analysis interface with filtering, pagination, and visualization tools.

• BacklinksPage.tsx — Entry point for the backlinks view
• BacklinksTable.tsx — Data table with sorting and selection
• BacklinksToolbarMenus.tsx — Filter and action menus

Source: [src/client/features/backlinks/BacklinksPage.tsx](https://github.com/every-app/open-seo/blob/main/src/client/features/backlinks/BacklinksPage.tsx)

Rank Tracking

The Rank Tracking feature manages SERP position monitoring with configuration modals and trend visualization.

• RankTrackingTable.tsx — Position history table
• RankTrackingConfigModal.tsx — Settings and scheduling UI
• RankTrackingTrendChart.tsx — Line chart for position changes

Source: [src/client/features/rank-tracking/RankTrackingTable.tsx](https://github.com/every-app/open-seo/blob/main/src/client/features/rank-tracking/RankTrackingTable.tsx)

Onboarding

The Onboarding feature guides new users through Google Search Console connection, API key setup, and initial configuration.

• OnboardingChat.tsx — Conversational setup assistant
• SearchConsoleOnboardingStep.tsx — GSC-specific connection step

Source: [src/client/features/onboarding/OnboardingChat.tsx](https://github.com/every-app/open-seo/blob/main/src/client/features/onboarding/OnboardingChat.tsx)

Saved Keywords

The Saved Keywords feature handles keyword portfolio management with tagging, filtering, and bulk operations.

• SavedKeywordsTable.tsx — Paginated keyword list
• SavedKeywordsTagFilter.tsx — Tag-based filtering interface

Source: [src/client/features/saved-keywords/SavedKeywordsTable.tsx](https://github.com/every-app/open-seo/blob/main/src/client/features/saved-keywords/SavedKeywordsTable.tsx)

Integrations

The Integrations feature provides UI for connecting third-party services like Google OAuth and DataForSEO.

• IntegrationConnectionCard.tsx — Service connection cards
• GoogleOAuthSetupWarning.tsx — OAuth-specific alerts and guidance

Source: [src/client/features/integrations/IntegrationConnectionCard.tsx](https://github.com/every-app/open-seo/blob/main/src/client/features/integrations/IntegrationConnectionCard.tsx)

Layout and Shared UI Components

Reusable UI primitives live outside the feature folders to enable consistent design across the application.

AppShell and Layout

The AppShell component serves as the main application wrapper, providing the sidebar, top navigation, and theme handling.

• AppShell.tsx — Main layout container
• AppShellParts.tsx — Decomposed shell components

Source: [src/client/layout/AppShell.tsx](https://github.com/every-app/open-seo/blob/main/src/client/layout/AppShell.tsx)

Common Components

The src/client/components/ directory houses shared UI pieces used across multiple features:

• Sidebar.tsx — Primary navigation sidebar
• Modal.tsx — Reusable dialog container
• SafeExternalLink.tsx — Security-hardened external link
• SegmentedToggle.tsx — Multi-option toggle control

Source: [src/client/components/Sidebar.tsx](https://github.com/every-app/open-seo/blob/main/src/client/components/Sidebar.tsx)

Route-Level Organization in src/routes

Route files map directly to URL paths using a file-system-based router. These components are typically lightweight, importing feature components from src/client/features/.

// Example: A simple page component in `src/routes`
export default function VerifyEmail() {
  return (
    <section className="p-4">
      <h1>Verify your email</h1>
      {/* …form elements… */}
    </section>
  );
}
// Path: src/routes/verify-email.tsx

Routes can be nested using underscore prefixes like _app/ and _project/ to create layout boundaries without exposing those segments in the URL.

Component Import Patterns

Feature components import shared UI pieces using path aliases, keeping import statements clean and refactorable:

// Example: Using a shared UI piece inside a feature component
import { Sidebar } from '@/client/components/Sidebar';

export function RankTrackingPage() {
  return (
    <>
      <Sidebar />
      <RankTrackingTable />
    </>
  );
}
// Path: src/client/features/rank-tracking/RankTrackingPage.tsx

Routing Infrastructure

Two critical files wire the route structure together:

• src/router.tsx — Central routing definition that imports route files and configures the router instance
• src/routeTree.gen.ts — Generated TypeScript mapping from the file-based route tree

Source: [src/router.tsx](https://github.com/every-app/open-seo/blob/main/src/router.tsx)

Summary

• src/routes/ contains thin page components mapped to URLs, generated by a file-system router
• src/client/features/ organizes UI by product capability, with each feature owning its pages, tables, charts, and supporting components
• src/client/layout/ and src/client/components/ provide reusable UI primitives shared across features
• src/shared/ holds pure TypeScript utilities with no JSX dependencies
• The architecture enables code splitting by feature, clear import boundaries, and rapid feature location by functional domain

Frequently Asked Questions

What routing framework does Open-SEO use?

Open-SEO uses a Remix-style file-system router with generated type definitions. The src/router.tsx file configures the router instance while src/routeTree.gen.ts provides TypeScript-safe route mappings. Underscore-prefixed folders like _app/ create layout nesting without URL segments.

How do I add a new feature to Open-SEO?

Create a new folder under src/client/features/ following the existing naming convention (kebab-case). Include your page component, table components, and any feature-specific subcomponents. Import your page into the appropriate route file or create a new route under src/routes/ that renders your feature component.

Why are route files separate from feature components?

This separation maintains a single source of truth for URL structure while allowing feature code to evolve independently. Route files handle framework-specific concerns like data loading and error boundaries, while feature components focus purely on presentation and user interaction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}