# Files Present in the Root of the Open‑SEO Repository: A Complete Developer Guide

> Explore the root of the open-seo repository. Discover over 20 essential files for Cloudflare Workers, Docker, CLI auth, and more. Your complete developer guide.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: developer-guide
- Published: 2026-09-11

---

**The root directory of the every-app/open-seo repository contains 20+ configuration files, deployment scripts, and entry points including `wrangler.jsonc` for Cloudflare Workers configuration, `Dockerfile.selfhost` for containerization, and [`cli-auth.ts`](https://github.com/every-app/open-seo/blob/main/cli-auth.ts) for CLI authentication utilities.**

The **open-seo** codebase is a Cloudflare Workers-based platform for SEO optimization and auditing. Understanding the files present in the root of the open-seo repository is essential for developers configuring deployments, managing database migrations, or extending the application's CLI capabilities as implemented in every-app/open-seo. These top-level files define the project skeleton while the bulk of application logic resides in subdirectories like `src/`, `drizzle/`, and `docs/`.

## Project Configuration Files

The open-seo repository root houses several critical configuration files that drive TypeScript compilation and Cloudflare Workers deployment.

### TypeScript and Wrangler Configuration

The [`tsconfig.json`](https://github.com/every-app/open-seo/blob/main/tsconfig.json) file contains the TypeScript compiler options for the entire project, enforcing strict type checking and modern ES module output. Alongside it, `wrangler.jsonc` and `wrangler.audit.jsonc` manage Cloudflare Workers deployment settings, defining **account IDs**, **route bindings**, and **KV namespace** configurations.

The [`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts) file provides TypeScript type definitions for the Cloudflare Worker environment, ensuring type safety when accessing bindings like `env.DB` or `env.CACHE` within the application code.

### Lock Files and Skills Configuration

The repository includes [`skills-lock.json`](https://github.com/every-app/open-seo/blob/main/skills-lock.json), which tracks enabled skills and capabilities for the AI agent system, and `.npmrc` for npm registry configuration and authentication token management during package installation.

## Build and Deployment Scripts

Self-hosting and containerization are supported through dedicated Docker configurations located at the repository root.

### Docker Self-Hosting Setup

The `Dockerfile.selfhost` defines a multi-stage build process optimized for production deployments, while [`docker-entrypoint.sh`](https://github.com/every-app/open-seo/blob/main/docker-entrypoint.sh) provides the initialization script that configures runtime environment variables and starts the worker process. These files enable developers to deploy the open-seo platform on any container-compatible infrastructure.

### Orchestration Configuration

The [`compose.yaml`](https://github.com/every-app/open-seo/blob/main/compose.yaml) file (Docker Compose configuration) simplifies local development and testing by orchestrating the worker container alongside dependent services. This allows developers to spin up the entire stack using `docker-compose up` without manual configuration.

## Runtime Entry Points

Several TypeScript files in the root directory serve as executable entry points for different operational modes.

### Worker Initialization

[`alchemy.run.ts`](https://github.com/every-app/open-seo/blob/main/alchemy.run.ts) functions as the primary Cloudflare Worker entry point, importing the application logic from `src/` and binding it to the Workers runtime. The [`alchemy.preview-access.run.ts`](https://github.com/every-app/open-seo/blob/main/alchemy.preview-access.run.ts) and [`alchemy.access.ts`](https://github.com/every-app/open-seo/blob/main/alchemy.access.ts) files handle specialized deployment scenarios, including preview environment access control and staging configurations.

### CLI Utilities

The [`cli-auth.ts`](https://github.com/every-app/open-seo/blob/main/cli-auth.ts) script provides a command-line interface for generating and validating authentication tokens required for API access. This utility interacts directly with the Cloudflare Workers authentication system and can be executed via Node.js from the repository root.

## Documentation and Repository Metadata

Human-readable documentation at the root level helps onboard new contributors.

The [`README.md`](https://github.com/every-app/open-seo/blob/main/README.md) contains the quick-start guide and high-level architecture overview, while [`CLAUDE.md`](https://github.com/every-app/open-seo/blob/main/CLAUDE.md) and [`AGENTS.md`](https://github.com/every-app/open-seo/blob/main/AGENTS.md) provide specific context for AI-assisted development workflows. The `LICENSE` file defines the open-source licensing terms governing the codebase.

## Hidden Tooling Configuration

Several dotfiles in the root directory configure development tools and enforce code quality standards.

- `.gitignore` – Specifies untracked files and directories (node_modules, build outputs, environment files)
- `.prettierignore` – Excludes files from code formatting
- [`.oxlintrc.json`](https://github.com/every-app/open-seo/blob/main/.oxlintrc.json) – Configures the Oxlint JavaScript/TypeScript linter rules
- `.npmrc` – Controls npm behavior and registry settings

These hidden files ensure consistent development environments across different machines and CI/CD pipelines.

## Database Migration Configuration

The open-seo repository supports multiple database backends through drizzle-orm, with configuration files located at the root.

The [`drizzle-prod.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle-prod.config.ts) configures migrations for SQLite (production), while [`drizzle-pg.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle-pg.config.ts) handles PostgreSQL-specific settings. These files define the migration folder paths, connection strings, and schema definitions required by the drizzle-kit CLI tool.

## Practical Usage Examples

### Loading Cloudflare Worker Configuration

When developing worker modules, reference the root configuration files to ensure type safety and configuration consistency:

```typescript
// src/worker.ts
import type { WorkerConfiguration } from '../worker-configuration.d.ts';
import config from '../wrangler.jsonc' assert { type: 'json' };

export const initWorker = (cfg: WorkerConfiguration) => {
  // Use configuration values such as `account_id`, `workers_dev`, etc.
};

```

### Running CLI Authentication

Execute the authentication utility directly from the repository root:

```bash
node cli-auth.ts --token <YOUR_TOKEN>

```

This command validates the provided token against the Cloudflare Workers authentication endpoints and stores valid credentials for subsequent API calls.

### Building the Self-Hosted Docker Image

Deploy the application locally using the provided Docker configuration:

```bash
docker build -f Dockerfile.selfhost -t open-seo-selfhost .
docker run -p 8787:8787 open-seo-selfhost

```

This binds port 8787 (the standard Cloudflare Workers port) to your local machine, allowing you to test the full application stack outside of Cloudflare's hosted infrastructure.

## Summary

- The **open-seo repository root** contains configuration files for TypeScript ([`tsconfig.json`](https://github.com/every-app/open-seo/blob/main/tsconfig.json)), Cloudflare Workers (`wrangler.jsonc`), and database migrations ([`drizzle-prod.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle-prod.config.ts)).
- **Deployment scripts** including `Dockerfile.selfhost` and [`docker-entrypoint.sh`](https://github.com/every-app/open-seo/blob/main/docker-entrypoint.sh) enable containerized self-hosting outside of Cloudflare's infrastructure.
- **Runtime entry points** such as [`alchemy.run.ts`](https://github.com/every-app/open-seo/blob/main/alchemy.run.ts) and [`cli-auth.ts`](https://github.com/every-app/open-seo/blob/main/cli-auth.ts) provide executable paths for the worker and command-line utilities.
- **Hidden configuration files** (`.gitignore`, [`.oxlintrc.json`](https://github.com/every-app/open-seo/blob/main/.oxlintrc.json), `.npmrc`) maintain code quality and development environment consistency.

## Frequently Asked Questions

### What is the purpose of `wrangler.jsonc` in the open-seo repository?

The `wrangler.jsonc` file configures the Cloudflare Workers deployment environment, specifying **account IDs**, **route patterns**, **KV namespace bindings**, and **compatibility dates**. This JSONC (JSON with Comments) file is consumed by the Wrangler CLI during deployment and development server operations.

### How do I self-host the open-seo application using root-level files?

Use the `Dockerfile.selfhost` and [`docker-entrypoint.sh`](https://github.com/every-app/open-seo/blob/main/docker-entrypoint.sh) files to build a containerized instance. Run `docker build -f Dockerfile.selfhost -t open-seo .` followed by `docker run -p 8787:8787 open-seo` to start the service locally on port 8787, bypassing the need for Cloudflare's hosted Workers platform.

### What database configurations are available in the root directory?

The repository includes [`drizzle-prod.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle-prod.config.ts) for SQLite production migrations and [`drizzle-pg.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle-pg.config.ts) for PostgreSQL connections. These files configure the drizzle-orm migration tool, specifying schema paths, connection URLs, and dialect-specific options for each supported database backend.

### Are there CLI utilities available in the root directory?

Yes, the [`cli-auth.ts`](https://github.com/every-app/open-seo/blob/main/cli-auth.ts) file provides a command-line authentication utility for generating and validating API tokens. This script can be executed with Node.js to manage access credentials required for interacting with the open-seo platform's protected endpoints.