🛠️ FACK API'S

A premium, self-hostable, node-based mock API platform for modern frontend & backend decoupled workflows.

---

Fack API's is a zero-configuration, self-hostable mock API platform designed to streamline decoupled software development. It functions as a flexible, high-fidelity mock backend that allows frontend and mobile teams to build and test code independently. With a graphical node canvas, a visual schema builder, custom chaos testing, and automatic TypeScript compilation, Fack API's accelerates your dev cycle from days to hours.

---

📸 Screenshots & Showcase

🗂️ Workspaces Dashboard	🎨 Node-Based Canvas Designer
⚙️ Workspace Settings & Safe Deletion

---

✨ Features

• 🌐 Clean Namespaces & Subdomain Routing: Direct endpoint access without unnecessary prefixes (e.g., http://localhost:3000/:projectSlug/... or subdomain http://:projectSlug.localhost:3000/...).
• 🎨 Visual Node Canvas: Design your endpoints graphically, customize HTTP methods, and simulate response pipelines with React Flow (@xyflow/react).
• 🌳 Nested JSON Schema Builder: Build complex response bodies with deep nestings (objects, arrays, primitives) without writing manual JSON schemas.
• 🎲 Faker.js Data Synthesizer: Connect any schema property to a rich library of data providers (names, images, finance, dates, addresses, internet).
• ⚡ Chaos Testing Simulator: Inject randomized delays (min/max latency) and specify failure rates (e.g., 5% of queries fail with a 500 error) to test UI resilience.
• ⚡ Bounded LRU Cache Layer: In-memory caching with configurable TTL and granular per-project and per-route cache invalidation.
• 📁 Type Contract Exporter: Automatically compile client-side TypeScript interfaces (.d.ts files) directly from your visual schemas.
• 📐 Agent-First Design System Linting: Validated with @shadcn/lint and ESLint 9 to ensure strict design system compliance.
• 🚀 Zero-Config Database: Backed by high-performance local SQLite wrapped in type-safe Drizzle ORM queries.
• 🐳 Native Containerization: Multi-stage Alpine Docker build with Docker Compose support for persistent storage and logging.

---

🏗️ Architecture

graph TD
    A["💻 Client / Frontend App"] -->|"1. API Request (/:projectSlug/* or Subdomain)"| D["🔀 Edge Proxy Layer (proxy.ts)"]
    B["🖥️ Dashboard UI"] -->|"Define Schema & Topology"| C[("💾 SQLite Database (Drizzle ORM)")]
    C -->|"Sync & Invalidate"| CACHE["⚡ LRU Cache Layer"]
    D -->|"Check Cache"| CACHE
    CACHE -.->|"Cache Miss"| D
    D -->|"2. Match Route (path-to-regexp)"| E["🎲 Mock Engine (JSF + Faker.js)"]
    E -->|"3. Add Latency & Chaos Sim"| F["⚡ Delay / Error Injector"]
    F -->|"4. Return Payload / Code"| A

    style A fill:#4F46E5,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#10B981,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#0F172A,stroke:#fff,stroke-width:2px,color:#fff
    style D fill:#F59E0B,stroke:#fff,stroke-width:2px,color:#fff
    style E fill:#6366F1,stroke:#fff,stroke-width:2px,color:#fff
    style F fill:#EF4444,stroke:#fff,stroke-width:2px,color:#fff
    style CACHE fill:#8B5CF6,stroke:#fff,stroke-width:2px,color:#fff

Loading

---

🛠️ Technology Stack

Component	Technology	Role
Framework	Next.js 16 (App Router + Turbopack)	Runtime container, SSR, and edge proxy handler
UI Library	React 19	Modern reactive component foundation
Flow Canvas	React Flow (@xyflow/react v12)	Visual node topology canvas
UI Primitives	Base UI (@base-ui/react) + shadcn/ui	Accessible headless and styled UI components
Styling	Tailwind CSS v4	High-performance utility styling
State Manager	Zustand v5 + Immer	Reactive schema editing and state persistence
ORM	Drizzle ORM (v0.45)	Database schema mapping and DDL generation
Database	SQLite (@libsql/client)	Fast, portable file-based database
Cache Layer	LRUCache (lru-cache)	Bounded in-memory route and data cache
Mock Engine	json-schema-faker + @faker-js/faker	Synthetic mock payload generation
Route Matcher	path-to-regexp	Express-style pattern matching
Type Compiler	json-schema-to-typescript	Compiles schema trees into TypeScript types
Code Quality	ESLint 9 + @shadcn/lint + Prettier	Linting and design system enforcement
Test Runner	Vitest v4	Fast unit and integration testing

---

🚀 Quick Start (Local Development)

Prerequisites

• Node.js 20.19+ (Node.js 26 recommended)
• pnpm (v10+ or v11+)

Step-by-Step Setup

1. Clone the repository:

   git clone https://github.com/Karelaking/fack-api.git
   cd fack-api

2. Install dependencies:

   pnpm install

3. Initialize the local database:

   pnpm drizzle-kit push

4. Boot the Next.js development server:

   pnpm dev

5. Open http://localhost:3000 for the landing page or http://localhost:3000/dashboard to manage your projects.

Zero-Config Local Mode (no API keys required)

You do not need any database API keys to run Fack. When DATABASE_URL and DATABASE_AUTH_TOKEN are left empty, the app runs in local mode:

• All project data — projects, endpoints, canvas state, notes, and settings — is stored in a private SQLite file on your disk:
  • Windows: %APPDATA%\fack-api\fack.db
  • macOS: ~/Library/Application Support/fack-api/fack.db
  • Linux: ~/.local/share/fack-api/fack.db
• Nothing leaves your machine. A legacy .\data\fack.db from older versions is migrated to the new location automatically on first boot.
• Override the location with FACK_DATA_DIR="D:/some/path" if you prefer.

The startup log confirms the active mode:

Storage mode: LOCAL — all project data stays on this machine (C:\Users\…\fack-api\fack.db)

Storage: Local ↔ Cloud

Adding database API keys switches storage to the cloud — the same code, data, and UI work in both modes:

1. Create a Turso database and copy your credentials into .env:

   DATABASE_URL="libsql://your-db.turso.io"
   DATABASE_AUTH_TOKEN="eyJ..."

2. Restart the app. It now runs in cloud mode and your data is reachable from any device you sign in on.

3. Copy existing local data over: open Settings → Storage & Data and use Import backup after downloading the backup from the local install, or copy everything from the terminal:

   pnpm db:copy --from local --to libsql://your-db.turso.io

Removing the keys and restarting returns you to private local storage. Backups are plain JSON / SQLite files on your disk:

pnpm db:backup            # copy the local DB file to <data-dir>/backups/
pnpm db:backup -- --remote # dump a remote database to JSON

Additional Scripts

• Run tests:

  pnpm test

• Run linter:

  pnpm lint

• Build production bundle:

  pnpm build

• Copy data between databases (local ⇄ cloud):

  pnpm db:copy --from local --to libsql://your-db.turso.io --dry-run

• Create a disk backup:

  pnpm db:backup

---

🧪 Running Tests

Every storage mode and the notes/backup features are covered by the Vitest suite:

pnpm test

Notable coverage (test/):

File	What it locks down
storage-mode.test.ts	Local-by-default resolution, cloud detection, token masking, fallbacks
config-store.test.ts	Atomic JSON config writes in the local data directory
notes.test.ts	Notes CRUD, pin ordering, validator limits
backup.test.ts	Export/restore round-trips, date revival, per-user ownership filtering
db-copy.test.ts	db:copy table ordering, upserts, dry runs

Test databases are written to data/test-fack-<pid>.db; clean them up with:

pnpm db:clean

---

🐳 Docker Deployment

You can self-host Fack API's on your local machine, homelab, or cloud server:

Option A: Build and Run with Docker Compose (Recommended)

Docker Compose sets up Fack API's alongside an optional PostgreSQL instance for request logging and Nginx for reverse proxying:

docker compose up -d

• Dashboard is accessible at http://localhost:3000 (or http://localhost:80 via Nginx).
• Database and project topologies are persisted in the fack-data Docker volume.

Option B: Pull Pre-built Image from Docker Hub

# Pull the Docker image
docker pull mkkatiyar277/fake-api:latest

# Run the container with persistent volume
docker run -d -p 3000:3000 -v fack-data:/app/data mkkatiyar277/fake-api:latest

---

📡 API Usage Example

Create a project with slug payment-service and add a route GET /v1/customers/:customerId:

Direct Path Routing:

curl -X GET http://localhost:3000/payment-service/v1/customers/cust_9923

Subdomain Routing (Local or Production):

curl -X GET http://payment-service.localhost:3000/v1/customers/cust_9923

Response Payload:

{
  "id": "cust_9923",
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "profile": {
    "avatar": "https://avatars.io/jane_smith",
    "jobTitle": "Lead System Architect"
  }
}

Query Parameter Filtering & Pagination

The mock engine supports dynamic pagination and query parameters out of the box:

curl -X GET "http://localhost:3000/payment-service/v1/customers?count=5"

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.