# Key Directories in the Open-SEO Repository: Complete Structure Guide

> Explore the every-app/open-seo repository's key directories. Understand the structure for TypeScript, React, server logic, UI components, assets, docs, migrations, and tooling.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: architecture
- Published: 2026-06-28

---

**The Open-SEO repository organizes its TypeScript and React codebase into eight distinct top-level directories that separate server logic, UI components, static assets, documentation, database migrations, and automation tooling.**

Open-SEO (maintained at `every-app/open-seo`) is a Cloudflare Workers-based SEO management platform. Understanding the **key directories within the Open-SEO repository** helps contributors navigate the modular architecture and maintain clean separation of concerns between the backend API, frontend interface, and operational resources.

## Core Application Source (`src/`)

The `src/` directory contains the primary TypeScript codebase and follows a clear separation between server-side logic and client-side components.

### Server Functions and Routes

Server-side API handlers live in `src/serverFunctions/`, while React route definitions reside in `src/routes/`. Shared utilities that bridge both environments are stored in `src/shared/`.

To add a new API endpoint, create a file in `src/serverFunctions/`:

```typescript
// src/serverFunctions/example.ts
import { json } from "remix";

export const GET = async () => json({ message: "Hello from Open-SEO!" });

```

### Client Components and Database Schema

The React UI components are housed in `src/client/`, and the Drizzle ORM schema definitions are located in `src/db/`. The central entry points include [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) (which wires up server functions) and [`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx) (the React router configuration).

Key schema definitions reside in [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts), which defines tables for rank tracking, keyword research, and user management.

## Static Assets and Marketing (`web/`)

The `web/` directory manages static marketing pages, blog content, and documentation sites built with Vite. Marketing content lives in `web/content/marketing/`, blog posts in `web/content/blog/`, and legal documentation in `web/content/legal/`.

To create a new marketing page, add a markdown file:

```markdown
<!-- web/content/marketing/new-feature.md -->

# New Feature

Learn how this feature boosts your SEO performance.

```

The build configuration is handled by [`web/vite.config.ts`](https://github.com/every-app/open-seo/blob/main/web/vite.config.ts), with static assets stored in `web/public/`.

## Documentation and Specifications (`docs/` and `specs/`)

Operational guides for developers and maintainers are stored in `docs/`. Files like [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md), [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md), and [`docs/MAINTAINERS.md`](https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md) cover deployment, authentication modes, and contribution guidelines.

The `specs/` directory contains living design documents that capture product decisions and architecture discussions. These markdown files (such as [`0001-project-scoping.md`](https://github.com/every-app/open-seo/blob/main/0001-project-scoping.md) and [`0003-google-search-console-integration.md`](https://github.com/every-app/open-seo/blob/main/0003-google-search-console-integration.md)) serve as the roadmap record.

## Database and Migration Management (`drizzle/`)

Database schema migrations for the D1 (SQLite) backend are defined in the `drizzle/` directory using Drizzle ORM. Each migration file (e.g., [`0025_loving_mojo.sql`](https://github.com/every-app/open-seo/blob/main/0025_loving_mojo.sql), [`0030_add_new_table.sql`](https://github.com/every-app/open-seo/blob/main/0030_add_new_table.sql)) includes SQL changes and metadata snapshots for version tracking.

Configuration is managed by [`drizzle.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle.config.ts) at the repository root.

Example migration structure:

```sql
-- drizzle/0030_add_new_table.sql
CREATE TABLE new_table (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL
);

```

## Automation and Testing (`scripts/` and `e2e/`)

Utility scripts for data seeding, release note generation, and housekeeping tasks are stored in `scripts/`. These TypeScript and SQL files (such as [`seed-rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/seed-rank-tracking.ts) and `release-notes.mjs`) are executed via the project's CLI.

The `e2e/` directory contains the Playwright test suite for validating critical user flows. Test files like [`keyword-research-navigation.spec.ts`](https://github.com/every-app/open-seo/blob/main/keyword-research-navigation.spec.ts) ensure end-to-end reliability across the application.

## Release Management (`release-notes/`)

Human-readable changelogs for every version are archived in `release-notes/`. Each file (e.g., [`v0.0.21.md`](https://github.com/every-app/open-seo/blob/main/v0.0.21.md), [`v0.0.9.md`](https://github.com/every-app/open-seo/blob/main/v0.0.9.md)) documents new features, bug fixes, and breaking changes for deployment tracking.

## Configuration and Entry Points

Root-level configuration files govern the entire project:

- **`wrangler.jsonc`** – Cloudflare Workers deployment configuration
- **[`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts)** – Build configuration for web assets and worker bundles
- **[`.github/workflows/ci.yml`](https://github.com/every-app/open-seo/blob/main/.github/workflows/ci.yml)** – Continuous integration pipeline for linting and testing
- **[`README.md`](https://github.com/every-app/open-seo/blob/main/README.md)** – High-level overview and setup instructions

## Summary

- The **`src/`** directory houses the core TypeScript application, including server functions, React routes, client components, and database schemas.
- **`web/`** contains static marketing assets and Vite-built documentation sites.
- **`docs/`** and **`specs/`** provide operational guides and architectural decision records.
- **`drizzle/`** manages D1 database migrations with Drizzle ORM configuration.
- **`scripts/`** and **`e2e/`** handle automation tasks and Playwright end-to-end testing.
- **`release-notes/`** archives versioned changelogs for release tracking.
- Root files like `wrangler.jsonc` and [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) configure deployment and application entry points.

## Frequently Asked Questions

### What is the difference between the `src/` and `web/` directories in Open-SEO?

The **`src/`** directory contains the dynamic application code including API endpoints, React components, and database logic that runs on Cloudflare Workers. The **`web/`** directory contains static markdown content, images, and Vite configuration for the marketing site and documentation that gets built into static HTML.

### Where should I add new database tables in the Open-SEO repository?

New tables should be defined in **[`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts)** for the TypeScript ORM types, and the actual migration SQL should be placed in the **`drizzle/`** directory following the sequential naming convention (e.g., [`0031_new_feature.sql`](https://github.com/every-app/open-seo/blob/main/0031_new_feature.sql)). Run migrations via the Drizzle CLI to apply changes to your D1 database.

### How do I run database migrations in Open-SEO?

Migrations are managed through the Drizzle configuration in **[`drizzle.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle.config.ts)**. Execute the migration command via the project's CLI (typically `pnpm db:migrate` or similar, depending on the package scripts) to apply SQL files from the `drizzle/` directory to your SQLite/D1 instance.

### Where should end-to-end tests be placed?

Playwright end-to-end tests belong in the **`e2e/`** directory at the repository root. Create spec files with descriptive names like [`feature-name.spec.ts`](https://github.com/every-app/open-seo/blob/main/feature-name.spec.ts) to test complete user workflows across the application interface.