Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wtyler2505/ProtoPulse/llms.txt

Use this file to discover all available pages before exploring further.

ProtoPulse runs entirely in your browser, but it needs a local backend and a PostgreSQL database to store your designs. This guide walks you through cloning the repository, configuring the environment, and launching the dev server — then shows you how to describe a circuit in plain English and watch the AI build it on screen.
ProtoPulse requires PostgreSQL 14 or newer and Node.js 20 or newer. Have a running PostgreSQL instance and a connection string ready before you begin.
1

Clone and install dependencies

Clone the repository and install npm dependencies:
git clone https://github.com/wtyler2505/ProtoPulse.git
cd ProtoPulse
npm install
This installs the full dependency tree — frontend (React 19, Vite 7, shadcn/ui) and backend (Express 5, Drizzle ORM, Anthropic SDK, Google Generative AI).
2

Configure your environment

Copy the example environment file and fill in the required values:
cp .env.example .env
Open .env in your editor. The two values you must set before the app will start are:
VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string, e.g. postgresql://user:pass@localhost:5432/protopulse
API_KEY_ENCRYPTION_KEYProduction32-byte hex string for AES-256-GCM encryption of stored AI API keys. Random per-boot in development.
PORTNoServer listen port. Defaults to 5000.
NODE_ENVNodevelopment or production. Defaults to development.
LOG_LEVELNodebug, info, warn, or error. Defaults to info.
TRUST_PROXYNoNumber of proxy hops to trust. Default 0 (off).
STREAM_TIMEOUT_MSNoActivity-based SSE timeout in milliseconds. Default 120000.
ADMIN_API_KEYNoShared secret for admin maintenance routes (/api/admin/*, /api/backup/*).
DB_POOL_MAXNoOverride for the database connection pool size.
CACHE_MAXNoOverride for the LRU cache size.
RATE_LIMIT_MAXNoOverride for the rate limit (requests per 15-minute window). Default 300.
DISABLE_AI_FALLBACKNoSet to 1 to disable automatic fallback between AI providers.
PARTS_CATALOG_V2NoSet to true to enable the unified parts catalog v2 read paths.
A minimal .env for local development looks like this:
DATABASE_URL=postgresql://protopulse:protopulse@localhost:5432/protopulse
NODE_ENV=development
LOG_LEVEL=info
PORT=5000
Never commit your .env file. It is already listed in .gitignore, but double-check before pushing. The API_KEY_ENCRYPTION_KEY is especially sensitive — it protects stored AI provider API keys.
3

Push the database schema

Drizzle ORM manages the 27-table PostgreSQL schema. Push it to your database with:
npm run db:push
This creates all tables, indexes, and constraints in a single step. You can verify the schema was applied by connecting to your database and listing the tables, or by running npm run db:studio to open Drizzle Studio in your browser.
4

Start the development server

npm run dev
The server starts on http://localhost:5000 with Vite HMR enabled. The terminal output confirms when both the Express backend and the Vite frontend are ready.Open http://localhost:5000 in your browser. You should see the ProtoPulse workspace with the Dashboard view open.
5

Seed demo data

An empty project gives you a blank canvas, which is great for real work but less useful for exploring the tool. Seed a fully populated demo project with a single API call:
curl -X POST http://localhost:5000/api/seed
This creates a sample project with architecture nodes, schematic components, BOM items, and validation issues pre-populated — giving you something real to explore in every view.
After seeding, switch to the Architecture tab to see a populated block diagram, then open Procurement to see the BOM with pricing and stock data.
6

Design your first circuit with the AI

The AI assistant lives in the right panel of the workspace. It isn’t just a chatbot — it has 82 tool actions that directly modify your design in real time.To design your first circuit, type a description in the chat panel and press Enter:
Design a 3.3V regulated power supply from USB-C input with
input protection and decoupling capacitors.
The AI will:
  1. Add architecture nodes for the USB-C connector, TVS diode, ferrite bead, LDO regulator, and decoupling caps
  2. Wire them together with typed signal edges
  3. Populate the BOM with specific part numbers, pricing, and package types
  4. Run a DRC to verify power domain consistency and flag any missing decoupling
  5. Stream every action to the screen in real time — all undoable
You can keep refining with follow-up messages: “Add an I2C temperature sensor to the design” or “What’s the recommended bypass capacitor value for this LDO?”

​
Available npm scripts

ScriptDescription
npm run devDev server with Vite HMR on port 5000
npm run buildProduction build (esbuild backend + Vite frontend)
npm startRun the production build
npm run checkTypeScript type check — must pass with zero errors
npm run db:pushSync Drizzle schema to PostgreSQL
npm run db:generateGenerate migration files
npm run db:studioOpen Drizzle Studio
npm testRun all tests (54 files, 1,553 tests)
npm run test:watchVitest interactive watch mode
npm run test:coverageTests with v8 coverage report

​
Next steps

Workspace overview

Learn the three-panel layout and how to navigate between the eight design views.

AI assistant

See the full list of 82 tool actions and learn how to get the best results from the AI.

Architecture editor

Start your design with a system block diagram before moving to schematics.

Developer setup

Full developer reference: API endpoints, database schema, and contribution guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us