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

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/:

// 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 (which wires up server functions) and src/router.tsx (the React router configuration).

Key schema definitions reside in 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:

<!-- 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, 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, docs/LOCAL_DEVELOPMENT.md, and 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 and 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, 0030_add_new_table.sql) includes SQL changes and metadata snapshots for version tracking.

Configuration is managed by drizzle.config.ts at the repository root.

Example migration structure:

-- 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 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 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, 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 – Build configuration for web assets and worker bundles
• .github/workflows/ci.yml – Continuous integration pipeline for linting and testing
• 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 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 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). 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. 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 to test complete user workflows across the application interface.

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