Build against a mock backend from an OpenAPI contract.

1. 01

   Install dependencies

   Run pnpm install from the repository root.

2. 02

   Start PostgreSQL and Redis

   Run docker compose up -d.

3. 03

   Prepare Prisma

   Generate Prisma Client, then run migrations so the database has every column used by the server.

4. 04

   Start the workspace

   Run pnpm dev. Public web runs on 3000, server on 3001, protected app on 3002.

5. 05

   Create the first mock API

   Register, create a project, upload api.json or another OpenAPI 3.x schema, then open Playground.

pnpm install
docker compose up -d
pnpm --filter @ghostapi/server prisma:generate
pnpm --filter @ghostapi/server prisma:migrate
pnpm dev

GhostAPI has one load-bearing mental model: an uploaded schema becomes normalized endpoints, and every product surface works from those endpoints.

Project

The workspace for one mock API. It owns schemas, endpoints, environments, logs, settings, and members.

Schema

An uploaded OpenAPI document. GhostAPI validates it and converts it into a normalized schema.

Endpoint

A normalized method/path operation generated from the schema and mounted under /mock/{projectId}.

Saved response

A response body you edit and persist for a status code and media type.

Mock defaults

Project-wide behavior such as latency, error chance, auth simulation, and response mode.

Activity log

A captured request/response record used to debug frontend traffic.

apps/web

Public Next.js site and docs.

apps/app

Protected Vite workspace for projects, playground, logs, and settings.

apps/server

Hono API, auth, Prisma, schema ingestion, Scalar docs, and runtime orchestration.

packages/parser

OpenAPI validation, dereferencing, and normalization.

packages/runtime

Dynamic route matching and mock request serving.

packages/mock-engine

Schema-aware sample response generation.

packages/types

Shared DTOs, Zod schemas, and NormalizedEndpoint contracts.

Duplicate handling is intentionally explicit. Keeping existing endpoints protects local mock edits; overriding updates the project to match the new contract.

What you just did mirrors a real project: pick an endpoint, dial in mock behavior, send a request, read the response. The only difference is that real projects come from your uploaded OpenAPI schema instead of this seeded fixture.

The runtime should behave like a backend, but remain configurable enough to force loading, error, auth, and empty-state paths in the frontend.

Route matching

OpenAPI paths become runtime matchers, including path parameters.

Response choice

Saved responses win first; generated schema-aware responses fill gaps.

Latency

Project defaults or endpoint overrides delay responses for loading-state testing.

Error chance

Configurable failure simulation exercises frontend error states.

Auth simulation

Endpoints can require configured headers without implementing business auth.

General

Project identity, icon, active schema summary, and base environment snapshot.

Environments

Base URLs, reusable variables, shared headers, and CORS-related context.

Mock

Default latency, error chance, auth simulation, and response strategy.

Schema

Metadata, version history, validation, servers, and replacement flow.

Members

Invite preview, role selection, pending invites, and member removal.

Danger Zone

Replace schema, reset mocks, clear logs, archive, restore, and delete.

Sessions

Access and refresh cookies identify the signed-in app user.

CSRF

Mutating browser requests must send x-csrf-token.

Verification

New accounts verify email before normal sign-in.

Password reset

Reset tokens expire and avoid account enumeration.

Invitations

Invite tokens expire and must match the invited email.

Public site

pnpm --filter @ghostapi/web dev on port 3000.

Protected app

pnpm --filter @ghostapi/app dev on port 3002.

Backend

pnpm --filter @ghostapi/server dev on port 3001.

Prisma

pnpm --filter @ghostapi/server prisma:generate and prisma:migrate.

Checks

pnpm lint, pnpm typecheck, pnpm test, pnpm build, and pnpm format:check.