What Technologies Are Used in the Paperclip Backend? A Complete Stack Breakdown

The Paperclip backend runs on Node.js 20+ with TypeScript 5.7, Express for HTTP routing, Drizzle ORM for type-safe PostgreSQL access, and Vite for rapid development.

Paperclip is an open-source AI-powered workspace tool with a modern, developer-friendly backend architecture. This article examines the complete technology stack powering the paperclipai/paperclip repository, covering everything from the runtime environment to database access patterns and testing infrastructure.

Core Runtime and Language

Node.js 20+ Engine

The backend requires Node.js 20 or higher, enforced through the engines field in package.json:

{
  "engines": {
    "node": ">=20"
  }
}

This version requirement ensures access to modern JavaScript features, improved performance, and long-term support stability.

TypeScript 5.7

All server code is written in TypeScript 5.7 ("typescript": "^5.7.3"), providing:

• Static type safety across the entire codebase
• Modern ES-module support for clean imports/exports
• Compile-time error detection before deployment

The project uses tsx for direct TypeScript execution during development, eliminating separate compilation steps.

Web Framework: Express

The HTTP layer relies on Express, implemented through the @paperclipai/server package. Routing follows a clean modular pattern as seen in server/src/routes/health.ts:

// server/src/routes/health.ts
import { Router } from "express";

export const healthRouter = Router();

healthRouter.get("/", (req, res) => {
  res.json({ status: "ok", timestamp: Date.now() });
});

This file demonstrates the standard router pattern used throughout the API—exporting dedicated Router instances that get mounted in the main application.

Database Layer: PostgreSQL with Drizzle ORM

Drizzle ORM for Type-Safe Queries

Drizzle ORM serves as the primary database access layer, offering a lightweight, type-safe query builder. Service files throughout server/src/services/ import Drizzle helpers, such as in workspace-runtime.ts:

import { db } from "@paperclipai/db";
import { workspaces } from "@paperclipai/db/schema";

export async function getWorkspace(id: string) {
  const record = await db
    .select()
    .from(workspaces)
    .where(eq(workspaces.id, id));
  return record[0] ?? null;
}

This pattern guarantees that database queries are validated at compile time against the actual schema defined in packages/db/src/schema/*.ts.

PostgreSQL and PGlite

The backend supports dual database configurations:

• Production: Standard PostgreSQL instance
• Development: PGlite embedded database (packages/db config), enabling zero-config local development without external PostgreSQL setup

The pg driver handles communication with PostgreSQL, used internally by Drizzle.

Development Toolchain

Vite for Fast Builds

Vite powers the development server through vite.config.ts, providing:

• Hot module replacement for both server and UI
• Optimized production builds
• Fast cold starts

tsx for Script Execution

The pnpm dev command invokes tsx directly:

pnpm dev   # Executes `tsx ../scripts/dev-runner.ts watch`

This allows TypeScript files to run without pre-compilation, streamlining the development workflow.

Testing Infrastructure

Vitest for Unit and Integration Tests

Vitest (vitest.config.ts) handles the bulk of automated testing via pnpm test. It provides:

• Native TypeScript support
• Fast parallel test execution
• Jest-compatible APIs

Playwright for End-to-End Tests

Playwright (tests/e2e/playwright.config.ts) runs UI and API smoke tests through pnpm test:e2e, ensuring critical user workflows remain functional.

promptfoo for Evaluations

The stack includes promptfoo for AI prompt evaluations, supporting robust testing of LLM-powered features.

Package Management and Monorepo Structure

pnpm workspaces organize the codebase through pnpm-workspace.yaml, managing packages under the @paperclipai/* namespace:

• @paperclipai/server — HTTP API and routing
• @paperclipai/db — Database schema and connection management
• @paperclipai/ui — Frontend components
• Additional adapter and utility packages

This structure enforces clean boundaries between concerns while enabling code sharing.

CI/CD and Deployment

GitHub Actions automate the entire release pipeline through workflow YAMLs in .github/workflows/, covering:

• Linting and type-checking
• Test execution (Vitest and Playwright)
• Production deployments

Additional Build Utilities

Tool	Purpose
cross-env	Cross-platform environment variable handling
esbuild	Fast bundling and transpilation
ts-node	Alternative TypeScript execution (legacy support)

Summary

The Paperclip backend technology stack delivers:

• Type safety end-to-end — TypeScript plus Drizzle ORM eliminates entire classes of runtime errors
• Developer velocity — Vite, tsx, and PGlite enable sub-second feedback loops
• Production reliability — Node 20+ engine constraints, comprehensive test suites, and automated CI/CD
• Modular architecture — pnpm workspaces keep server, database, and UI concerns cleanly separated

Key files to explore further include server/src/routes/health.ts for Express patterns, server/src/services/workspace-runtime.ts for Drizzle usage, and packages/db/src/schema/*.ts for database definitions.

Frequently Asked Questions

Is Paperclip backend built with NestJS or Fastify?

No. The Paperclip backend uses Express as its web framework, not NestJS or Fastify. This is visible in routing files like server/src/routes/health.ts where Express's Router is imported directly and used without additional framework abstractions.

Why does Paperclip use Drizzle ORM instead of Prisma?

The repository employs Drizzle ORM for its lightweight, SQL-like query API and compile-time type safety without a heavy client generation step. Drizzle's approach matches well with the existing schema definitions in packages/db/src/schema/*.ts and avoids the migration complexity of schema-first tools.

Can I run the Paperclip backend without installing PostgreSQL?

Yes. The backend supports PGlite, an embedded PostgreSQL implementation, through the packages/db configuration. This allows developers to run the full application stack locally without configuring an external PostgreSQL instance.

What testing frameworks does the Paperclip backend use?

The backend uses Vitest for unit and integration tests and Playwright for end-to-end testing. Vitest handles API logic validation through pnpm test, while Playwright runs browser-based and API smoke tests via pnpm test:e2e.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}