How to Navigate the every-app/open-seo Repository Structure: A Complete Guide

The every-app/open-seo repository is organized as a TypeScript monorepo with distinct directories for server functions, database schemas, shared utilities, and client components, centered around TanStack Router and Server Functions.

The every-app/open-seo codebase powers an SEO management application built on modern React patterns. Understanding how to navigate this repository structure is essential for contributors, maintainers, and developers looking to self-host or extend the platform. The architecture follows a clear separation between frontend routes, backend API logic, and database abstractions that support both SQLite and Postgres dialects.

Top-Level Directory Layout

The repository root contains configuration files and six primary directories that separate concerns by technical responsibility:

• src/ – Core application code including server functions, React router configuration, shared utilities, and TypeScript type definitions.
• src/db/ – Database schema definitions for both SQLite and Postgres, plus migration scripts that handle the dual-dialect architecture.
• src/serverFunctions/ – TanStack Server Functions that expose backend APIs to the frontend and external AI agents.
• src/shared/ – Reusable client-side helpers for Google Search Console integration (gsc.ts), billing logic (billing.ts), and JSON handling (json.ts).
• src/client/ – UI components, layout files like AppShell.tsx, and TanStack Router wiring.
• scripts/ – Utility scripts including database migrations and CLI helpers such as migrate-d1-to-postgres.ts.
• e2e/ – End-to-end Playwright tests that drive the full application UI.

Additional directories include release-notes/, runbooks/, and docs/ (referenced from the README) for operational documentation. Build configuration lives in package.json, vite.config.ts, and pnpm-workspace.yaml at the repository root.

Core Entry Points and Bootstrapping

Four critical files serve as the primary entry points when exploring the codebase:

src/start.ts instantiates the TanStack React Start application and registers global middleware including CSRF protection and server-function handlers. This file serves as the application bootstrap.

src/router.tsx builds the TanStack Router using the generated routeTree, connecting URL paths to their corresponding page components and layouts.

src/serverFunctions/projects.ts demonstrates a fully-featured server function implementation. It includes authentication middleware (requireAuthenticatedContext), Zod validation schemas, and business logic delegation to ProjectService.

src/db/schema.ts acts as a central schema barrel that selects the appropriate dialect (SQLite for development, Postgres for production) at runtime and re-exports all tables under a unified namespace.

Architecture Flow: How the Pieces Fit Together

Understanding the data flow helps you navigate between layers when debugging or adding features.

Client to Router to Server Functions

The React frontend initializes routing through createTanStackRouter in src/router.tsx. Route handlers trigger TanStack Server Functions located under src/serverFunctions/, created using createServerFn and optionally wrapped by authentication middleware.

Server Functions to Services to Database

Server functions delegate to service classes (such as ProjectService) rather than querying the database directly. Services import tables from src/db/schema.ts, which abstracts the underlying database provider and dialect differences.

Shared Utilities and Type Safety

Reusable logic for external integrations resides in src/shared/ alongside their corresponding test files (for example, src/shared/gsc.test.ts validates Google Search Console helpers). All public API payloads undergo validation via Zod schemas stored in src/types/schemas/, ensuring compile-time and runtime type safety across the client-server boundary.

Practical Navigation Commands

Use these CLI commands from the repository root to explore the structure efficiently:

# List top-level directories

ls -1

# Show the tree of the source folder (depth 2)

git ls-tree -d --name-only HEAD src | xargs -I{} sh -c 'echo {}; tree -L 2 src/{}'

# Find where specific patterns appear (e.g., server function creation)

grep -R "createServerFn" -n src/serverFunctions

# Open key implementation files directly

code src/serverFunctions/projects.ts
code src/db/schema.ts

Essential Files Every Developer Should Know

These files provide the fastest path to understanding each architectural layer:

• README.md – Project overview, hosted version details, and self-hosting guidance.
• src/start.ts – Application bootstrap and middleware registration.
• src/router.tsx – TanStack Router configuration and route tree integration.
• src/serverFunctions/projects.ts – Production example of auth, validation, and service patterns.
• src/db/schema.ts – Dual-dialect database schema exports.
• src/shared/gsc.ts – Google Search Console integration implementation.
• src/types/schemas/projects.ts – Zod schema definitions for project data structures.
• src/client/layout/AppShell.tsx – Main UI layout component consumed by the router.
• scripts/migrate-d1-to-postgres.ts – Reference script for database migration strategies.

Summary

• The every-app/open-seo repository follows a TypeScript monorepo structure with clear separation between src/serverFunctions/, src/client/, src/db/, and src/shared/.
• Database portability is handled centrally in src/db/schema.ts, which exports unified table definitions for both SQLite and Postgres.
• Application bootstrap occurs in src/start.ts, while routing logic lives in src/router.tsx using TanStack Router.
• Server functions in src/serverFunctions/ represent the API layer, delegating to services and validating inputs with Zod schemas from src/types/schemas/.
• Shared utilities in src/shared/ provide reusable logic for billing, GSC integration, and JSON processing with co-located test files.

Frequently Asked Questions

Where is the database schema defined in the every-app/open-seo repository?

The database schema is defined in src/db/schema.ts, which implements a dual-dialect architecture. This file conditionally exports SQLite schemas for local development and Postgres schemas for production environments, allowing the same application code to run against different database engines without modification.

How does routing work in the open-seo codebase?

Routing is handled by TanStack Router, configured in src/router.tsx. The router consumes a generated routeTree to map URLs to React components, while server-side data fetching occurs through TanStack Server Functions located in src/serverFunctions/ rather than traditional API route handlers.

What is the purpose of the src/serverFunctions/ directory?

The src/serverFunctions/ directory contains TanStack Server Functions that serve as the backend API layer. Each file exports functions created with createServerFn that can include middleware for authentication (like requireAuthenticatedContext) and Zod validation before delegating to service classes for business logic execution.

How do I migrate from SQLite to Postgres in this repository?

The repository includes a reference migration script at scripts/migrate-d1-to-postgres.ts that demonstrates strategies for moving data from D1 (Cloudflare's SQLite offering) to Postgres. The src/db/schema.ts file already supports both dialects, so migrations primarily involve data transfer rather than schema changes.

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