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

> Master the every-app/open-seo repository structure. This guide breaks down its TypeScript monorepo design for server functions, schemas, utilities, and client components, using TanStack Router.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/every-app/open-seo/blob/main/gsc.ts)), billing logic ([`billing.ts`](https://github.com/every-app/open-seo/blob/main/billing.ts)), and JSON handling ([`json.ts`](https://github.com/every-app/open-seo/blob/main/json.ts)).
- **`src/client/`** – UI components, layout files like [`AppShell.tsx`](https://github.com/every-app/open-seo/blob/main/AppShell.tsx), and TanStack Router wiring.
- **`scripts/`** – Utility scripts including database migrations and CLI helpers such as [`migrate-d1-to-postgres.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/package.json), [`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts), and [`pnpm-workspace.yaml`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```bash

# 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`](https://github.com/every-app/open-seo/blob/main/README.md)** – Project overview, hosted version details, and self-hosting guidance.
- **[`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)** – Application bootstrap and middleware registration.
- **[`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx)** – TanStack Router configuration and route tree integration.
- **[`src/serverFunctions/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/projects.ts)** – Production example of auth, validation, and service patterns.
- **[`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts)** – Dual-dialect database schema exports.
- **[`src/shared/gsc.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/gsc.ts)** – Google Search Console integration implementation.
- **[`src/types/schemas/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/projects.ts)** – Zod schema definitions for project data structures.
- **[`src/client/layout/AppShell.tsx`](https://github.com/every-app/open-seo/blob/main/src/client/layout/AppShell.tsx)** – Main UI layout component consumed by the router.
- **[`scripts/migrate-d1-to-postgres.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts), which exports unified table definitions for both SQLite and Postgres.
- **Application bootstrap** occurs in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts), while routing logic lives in [`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) file already supports both dialects, so migrations primarily involve data transfer rather than schema changes.