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

> Explore the Open-SEO repository structure discover the main directories including src e2e scripts drizzle-pg and more Master the project organization with this comprehensive guide

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

---

**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`](https://github.com/every-app/open-seo/blob/main/src/start.ts), which serves as the application bootstrap, and [`src/routes/verify-email.tsx`](https://github.com/every-app/open-seo/blob/main/src/routes/verify-email.tsx), demonstrating server-rendered React routes. Type definitions are centralized in schemas like [`src/types/schemas/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/projects.ts).

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/e2e/keyword-research-navigation.spec.ts) and [`e2e/domain-overview-filters.spec.ts`](https://github.com/every-app/open-seo/blob/main/e2e/domain-overview-filters.spec.ts).

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/XXXX_description.sql), such as [`drizzle-pg/0013_sleepy_black_tarantula.sql`](https://github.com/every-app/open-seo/blob/main/drizzle-pg/0013_sleepy_black_tarantula.sql) and [`drizzle-pg/0000_fixed_nico_minoru.sql`](https://github.com/every-app/open-seo/blob/main/drizzle-pg/0000_fixed_nico_minoru.sql).

```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`](https://github.com/every-app/open-seo/blob/main/scripts/migrate-d1-to-postgres.ts) for production database migrations and [`scripts/seed-rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/scripts/seed-rank-tracking.ts) for populating initial rank tracking data.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/.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`](https://github.com/every-app/open-seo/blob/main/.greptile/rules.md) and [`.greptile/files.json`](https://github.com/every-app/open-seo/blob/main/.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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/rules.md) and [`files.json`](https://github.com/every-app/open-seo/blob/main/files.json)) for the Greptile linting engine. This tool enforces code quality standards and architectural patterns automatically across the repository.