Main Directories in the Open-SEO Project: Complete Repository Structure Guide

The Open-SEO repository organizes its TypeScript serverless codebase into eight primary directories: src/ for core application logic, e2e/ for Playwright tests, scripts/ for automation tasks, public/ for static assets, drizzle-pg/ for PostgreSQL migrations, specs/ for technical documentation, .github/ for CI/CD workflows, and .greptile/ for linting rules.

Open-SEO is a TypeScript-first, serverless application built for the Cloudflare Workers platform. Understanding the main directories in the open-seo project is essential for navigating its architecture, which strictly separates concerns between application code, database schema, testing infrastructure, and operational configuration according to the every-app/open-seo source code.

The src/ Directory: Core Application Logic

The src/ folder contains the heart of the application, housing server functions, React routes, Zod type definitions, and utility modules. This is where the Cloudflare Worker entry point and request routing logic reside.

Representative files include src/start.ts, which serves as the application bootstrap, and src/routes/verify-email.tsx, demonstrating server-rendered React routes. Type definitions are centralized in schemas like src/types/schemas/projects.ts.

// src/start.ts
import { createServer } from '@cloudflare/worker';
import { router } from './router';

export default createServer(router);

The e2e/ Directory: Playwright End-to-End Tests

All browser-level testing lives in the e2e/ directory, powered by Playwright. These specifications verify critical user flows such as keyword research navigation and domain overview filtering before deployment.

Key test files include e2e/keyword-research-navigation.spec.ts and e2e/domain-overview-filters.spec.ts.

// e2e/keyword-research-navigation.spec.ts
import { test, expect } from '@playwright/test';

test('search keyword flow', async ({ page }) => {
  await page.goto('/keyword-research');
  await page.fill('#search', 'open seo');
  await page.click('button[type=submit]');
  await expect(page).toHaveURL(/results/);
});

The drizzle-pg/ Directory: PostgreSQL Migrations

Database schema evolution is managed through the drizzle-pg/ folder, which stores versioned SQL migration files for the Postgres database using Drizzle ORM.

Files follow the naming pattern XXXX_description.sql, such as drizzle-pg/0013_sleepy_black_tarantula.sql and drizzle-pg/0000_fixed_nico_minoru.sql.

-- drizzle-pg/0013_sleepy_black_tarantula.sql
CREATE TABLE IF NOT EXISTS rank_tracking (
  id SERIAL PRIMARY KEY,
  keyword TEXT NOT NULL,
  position INTEGER,
  tracked_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

The scripts/ Directory: Automation and Data Management

Project-wide helper scripts for data migration, seeding, CI tasks, and release automation reside in scripts/. These TypeScript utilities handle one-off operations, database transitions, and maintenance tasks outside the main application flow.

Notable files include scripts/migrate-d1-to-postgres.ts for production database migrations and scripts/seed-rank-tracking.ts for populating initial rank tracking data.

// scripts/seed-rank-tracking.ts
import { db } from '../src/db';
await db.rank_tracking.createMany([
  { keyword: 'open seo', position: 1 },
  { keyword: 'seo tools', position: 3 },
]);

The public/ Directory: Static Assets

Static files served directly to browsers without server-side processing—such as favicons, web manifests, and branding images—are stored in public/. The build process copies these assets to the distribution folder verbatim.

Key files include public/favicon.png and public/site.webmanifest.

The specs/ Directory: Technical Documentation

Design specifications, architecture decision records, and technical documentation live in specs/ as Markdown files. This directory preserves the rationale behind server function implementations and long-term system design.

Example: specs/0001-project-scoping-for-server-functions.md details the architectural approach for server functions.

The .github/ Directory: CI/CD Configuration

GitHub-specific configurations, including workflow definitions for continuous integration and repository governance, are housed in .github/. The .github/workflows/ci.yml file defines the pipeline that runs tests, linting, and worker builds on every pull request, while CODEOWNERS establishes review requirements.

The .greptile/ Directory: Static Analysis Rules

Repository-wide static analysis configuration used by the Greptile linting engine resides here. Files like .greptile/rules.md and .greptile/files.json enforce code quality standards and architectural constraints across the entire codebase.

Summary

• src/ contains the core TypeScript application logic, routing, and Cloudflare Worker entry point at src/start.ts.
• e2e/ houses Playwright tests verifying critical user workflows like keyword research navigation.
• scripts/ provides automation for database migrations, seeding, and deployment tasks.
• drizzle-pg/ manages PostgreSQL schema migrations via Drizzle ORM using numbered SQL files.
• public/ serves static assets including favicons and web manifests.
• specs/ documents technical specifications and design decisions in Markdown format.
• .github/ configures CI/CD pipelines, issue templates, and repository governance.
• .greptile/ defines static analysis rules for automated code quality enforcement.

Frequently Asked Questions

What is the entry point for the Open-SEO application?

The main entry point is src/start.ts, which imports the application router and creates the Cloudflare Worker server using the createServer(router) function. This file initializes the runtime environment for the serverless platform.

Where are database migrations stored in Open-SEO?

Database migrations for PostgreSQL are stored in the drizzle-pg/ directory as numbered SQL files (e.g., 0013_sleepy_black_tarantula.sql), managed by Drizzle ORM. These files track schema evolution and are applied sequentially during deployment.

How does Open-SEO handle end-to-end testing?

The project uses Playwright for end-to-end testing, with all test specifications located in the e2e/ directory. These tests simulate real browser interactions to verify critical user flows, such as navigating to the keyword research page and submitting search queries.

What is the purpose of the .greptile/ directory?

The .greptile/ directory contains static analysis rules and configuration files (like rules.md and files.json) for the Greptile linting engine. This tool enforces code quality standards and architectural patterns automatically across the repository.

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