# What Is the Purpose of the Audit System in Open‑SEO? A Technical Deep Dive

> Discover the purpose of the audit system in Open-SEO. Automatically crawl, analyze with Lighthouse, and fix SEO issues with reproducible reports. Learn more.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: deep-dive
- Published: 2026-08-21

---

**The audit system in open-seo automatically crawls websites, evaluates pages using Lighthouse, detects SEO issues, and delivers reproducible site audit reports while enforcing plan limits and maintaining temporary crawl state.**

The audit system serves as the backbone of Open‑SEO’s Site Audit feature, providing a complete, reproducible workflow that examines websites for SEO health. According to the open‑seo source code, this system orchestrates everything from URL discovery to performance analysis, surfacing structured issues like missing meta tags and blocked pages that power the product’s marketing descriptions and user dashboards.

## Core Responsibilities of the Site Audit Pipeline

Open‑SEO’s audit system functions as a **managed, scalable site‑crawling pipeline**. It performs multi‑phase crawling, runs Lighthouse performance checks, and persists results for historical analysis. The system is designed to be resource‑aware and self‑healing, ensuring reliable operation even in hosted SaaS environments where multiple users run simultaneous audits.

## Architectural Components of the Audit System

### AuditService Orchestrates the Lifecycle

Located at [`src/server/features/audit/services/AuditService.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/services/AuditService.ts), the **AuditService** manages the entire audit lifecycle. It resolves plan limits, creates audit records, launches Cloudflare Workflows, monitors execution status, and triggers cleanup upon completion or cancellation. The service also includes a `reconcileRunningAudit` method (line 37) that detects and recovers orphaned workflows, ensuring the system remains consistent after crashes or interruptions.

### AuditWorkflow Executes Multi‑Phase Crawls

The [`src/server/workflows/siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/siteAuditWorkflowPhases.ts) file defines the **AuditWorkflow**, which executes sequential crawl phases: discovery, URL sanitization, page analysis, Lighthouse runs, and issue detection. This workflow structure ensures that each stage completes successfully before the next begins, creating a deterministic audit process.

### AuditRepository Persists Structured Data

Data persistence is handled by [`src/server/features/audit/repositories/AuditRepository.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/repositories/AuditRepository.ts). This layer stores audit metadata, crawled pages, Lighthouse results, and detected SEO issues in the database, enabling long‑term historical tracking and detailed reporting.

### Real‑Time Progress Tracking via KV Store

For immediate user feedback, [`src/server/lib/audit/progress-kv.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/progress-kv.ts) implements **AuditProgressKV**, a fast key‑value store that tracks URLs crawled versus total URLs. This allows the frontend to display real‑time progress bars during active audits without polling the primary database.

### Capacity Enforcement and Plan Limits

The `src/server/features/audit/services/audit‑capacity.ts` module enforces per‑plan restrictions, limiting pages per audit, concurrent audit jobs, and total capacity units. This prevents resource abuse in multi‑tenant deployments and ensures fair usage across billing tiers.

### Temporary State Management with AuditScratchpad

Crawl state management uses [`src/server/features/audit/AuditScratchpad.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/AuditScratchpad.ts) to hold temporary data such as discovered URLs. This scratchpad automatically cleans itself after a 7‑day alarm, preventing storage bloat from abandoned or failed audit attempts.

## API Surface and Frontend Integration

### Server Functions for Audit Operations

The [`src/serverFunctions/audit.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/audit.ts) file exposes the public API surface for audit management. Developers initiate audits through the `startAudit` method:

```typescript
// src/serverFunctions/audit.ts
await AuditService.startAudit({
  actorUserId,
  billingCustomer,
  projectId,
  startUrl,
  maxPages,
  lighthouseStrategy,
  limitTier,
});

```

Additional operations include status checking, result retrieval, and deletion:

```typescript
// Fetch current status
const status = await AuditService.getStatus(auditId, projectId);

// Retrieve complete results
const { audit, pages, lighthouse, issues } = await AuditService.getResults(
  auditId,
  projectId,
);

// Remove audit data
await AuditService.remove(auditId, projectId);

```

### Frontend Route Structure

User interfaces for the audit system reside in `src/routes/_project/p/$projectId/audit/*`. These routes render the audit dashboard, progress views, and detailed issue reports, consuming the server functions to provide a cohesive user experience.

## Reliability and Resource Management

### Self‑Healing Workflow Reconciliation

The audit system includes built‑in fault tolerance. The `reconcileRunningAudit` method in [`AuditService.ts`](https://github.com/every-app/open-seo/blob/main/AuditService.ts) periodically checks for audits stuck in a running state without active workflows, automatically resetting or cleaning them up to maintain system integrity.

### Automated Cleanup and Data Retention

Temporary crawl data stored in the AuditScratchpad expires after 7 days, while persistent results remain in the database indefinitely until explicitly deleted via the API. This tiered storage approach balances performance with long‑term audit history requirements.

## Summary

- The **audit system** in open‑seo provides automated website crawling and SEO analysis through a multi‑phase Cloudflare Workflow defined in [`siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/siteAuditWorkflowPhases.ts).
- **AuditService.ts** orchestrates the entire lifecycle, including plan limit validation, workflow initiation, and self‑healing reconciliation of orphaned processes.
- Real‑time progress tracking utilizes a dedicated KV store (`progress‑kv.ts`) to feed live UI updates without database load.
- Plan enforcement occurs via `audit‑capacity.ts`, preventing resource exhaustion in SaaS deployments.
- Temporary crawl state persists in [`AuditScratchpad.ts`](https://github.com/every-app/open-seo/blob/main/AuditScratchpad.ts) with automatic 7‑day expiration, while permanent results store in the repository layer.
- The complete API surface in [`src/serverFunctions/audit.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/audit.ts) enables starting, monitoring, retrieving, and deleting audits programmatically.

## Frequently Asked Questions

### How does the audit system handle concurrent audits?

The system enforces concurrency limits through `src/server/features/audit/services/audit‑capacity.ts`, which checks the user’s billing tier before allowing new audits to start. If the account has reached its concurrent audit limit or total capacity units, the `AuditService` rejects the request immediately, preventing resource starvation in multi‑tenant environments.

### What triggers the self‑healing mechanism for stuck audits?

The `reconcileRunningAudit` method inside [`src/server/features/audit/services/AuditService.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/services/AuditService.ts) (around line 37) periodically scans for audits marked as running but lacking active workflow instances. When detected, the system either resumes the workflow or marks the audit as failed with an appropriate error state, ensuring database consistency without manual intervention.

### How does the audit system track real‑time crawl progress?

During active crawls, the workflow updates [`src/server/lib/audit/progress-kv.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/progress-kv.ts) with the current URL count and total discovered pages. The frontend polls this KV store to render progress indicators, providing immediate visual feedback while keeping the primary database free of high‑frequency write operations.

### What happens to temporary crawl data after an audit completes?

The [`AuditScratchpad.ts`](https://github.com/every-app/open-seo/blob/main/AuditScratchpad.ts) component stores transient crawl state such as discovered URL queues. This data automatically expires after 7 days via configured alarms, regardless of whether the audit succeeded or failed. Permanent audit results, Lighthouse scores, and detected issues remain in the database until explicitly deleted through the `AuditService.remove()` method.