ProtoPulse System Architecture

ProtoPulse is a ~30,000-line TypeScript monorepo. The browser runs a React 19 single-page application; the server runs an Express 5 API that serves both the compiled frontend and all REST + SSE endpoints from a single process on port 5000. PostgreSQL stores all persistent state, accessed exclusively through Drizzle ORM. This page maps out how those layers connect.

High-level overview

Browser (React 19)
  │
  │  HTTP REST + Server-Sent Events
  ▼
Express 5 Server (:5000)
  ├── Middleware stack (Helmet, gzip, rate-limit, session auth)
  ├── 21 domain routers  (server/routes/)
  ├── 13 circuit routers (server/circuit-routes/)
  ├── AI engine          (server/ai.ts — Claude + Gemini, 82 tools, SSE streaming)
  └── Storage layer      (server/storage.ts — IStorage + DatabaseStorage + LRU cache)
        │
        ▼
      PostgreSQL (Drizzle ORM — shared/schema.ts)

Every request flows through a deterministic middleware stack before reaching a route handler. Route handlers validate input with Zod, call IStorage methods, and return JSON. The AI engine is the only path that opens a long-lived SSE stream back to the client.

Request lifecycle

Each incoming HTTP request passes through the following pipeline in order:

CSP nonce generation — a random nonce is attached to res.locals for Helmet’s Content-Security-Policy header
Helmet — sets security headers (CSP, HSTS, X-Frame-Options, etc.); CSP runs in reportOnly mode in development
Compression — gzip response bodies
Request ID — generates a UUID, attached as req.id and returned as X-Request-Id
API version header — appends X-API-Version: 1 to all responses
Rate limiter — 300 requests per 15-minute window per IP (10 req/15 min for auth endpoints)
JSON body parser — 1 MB default; individual routes override with payloadLimit()
CSRF check — validates Origin against Host for state-mutating requests
Request timeout — 30-second hard timeout
Session auth middleware — validates X-Session-Id, populates req.userId
Audit log — records authenticated mutations
Route handler — Zod validation → IStorage → response
Error handler — HttpError status-aware; messages are sanitized in production

Frontend
Backend
Database

Frontend architecture

The frontend lives entirely under client/src/ and is a React 19 single-page application built with Vite 7.

State management

There is no Redux or Zustand. All server state is managed by TanStack React Query v5 (@tanstack/react-query). Local ephemeral state uses React’s built-in useState and useReducer. The apiRequest() helper in client/src/lib/queryClient.ts wraps fetch and attaches the X-Session-Id header to every request.The central ProjectProvider context (client/src/lib/project-context.tsx) exposes 40+ state values and React Query mutations to the entire workspace. All views subscribe to this context rather than fetching data independently.

Routing

Client-side routing uses Wouter — a lightweight alternative to React Router. There are three routes:

/ — redirects to the project list
/projects/:id — ProjectWorkspace, the main three-panel layout
* — not-found.tsx (404)

UI layer

The component library is shadcn/ui (60+ primitives in client/src/components/ui/) backed by Radix UI for accessible headless primitives. Styling is Tailwind CSS v4 with CSS variable-based theming. The canvas views use:

@xyflow/react (React Flow v12) — Architecture diagram and circuit schematic canvas
Recharts — BOM price charts and simulation output plots
CodeMirror 6 — Firmware/code editor with syntax highlighting

Key components

Component	Path	Role
`ProjectWorkspace`	`pages/ProjectWorkspace.tsx`	Root three-panel layout: Sidebar + Main Views + Chat Panel
`Sidebar`	`components/layout/Sidebar.tsx`	Navigation, component library tree, history panel
`ArchitectureView`	`components/views/ArchitectureView.tsx`	React Flow block diagram canvas
`SchematicCanvas`	`components/circuit-editor/SchematicCanvas.tsx`	Circuit schematic editor
`ChatPanel`	`components/panels/ChatPanel.tsx`	AI chat, SSE streaming, action parsing and execution
`ExportPanel`	`components/panels/ExportPanel.tsx`	Multi-format export UI (KiCad, Eagle, Gerber, SPICE, etc.)
`ProcurementView`	`components/views/ProcurementView.tsx`	BOM management and snapshot diff
`ValidationView`	`components/views/ValidationView.tsx`	DRC/ERC results with “Mark Resolved” actions

Context providers

Domain-specific state is split across several React contexts co-located under client/src/lib/contexts/:

Context	Purpose
`ProjectProvider`	Central 40+ state values; React Query mutations for all project data
`AuthContext`	Session state and current user
`ArchitectureContext`	Architecture view local state
`BomContext`	BOM view state and filters
`ChatContext`	Chat history and streaming state
`ValidationContext`	Validation issue list and filter state
`HistoryContext`	Action history list
`OutputContext`	System log entries

Backend architecture

The backend is a Node.js process running Express 5 with TypeScript compiled on-the-fly by tsx.

Entry point

server/index.ts bootstraps the application: it validates environment variables, registers the middleware stack, mounts all route barrels, attaches Vite as static middleware (in development) or serves dist/public/ (in production), registers the collaboration WebSocket server, and starts the HTTP server with graceful shutdown handling.

Route organization

Routes are split across two barrels:

server/routes.ts — registers 21 domain routers covering auth, projects, architecture, BOM, validation, chat, history, components, settings, admin, batch analysis, project import/export, BOM snapshots, SPICE models, design preferences, component lifecycle, and more
server/circuit-routes.ts — registers 13 circuit-specific routers covering circuit designs, instances, nets, wires, vias, netlist generation, hierarchical ports, autorouting, simulation, and all circuit export formats

All route handlers use asyncHandler() from server/routes/utils.ts to propagate async errors into Express’s error middleware. Input validation uses Zod schemas generated from shared/schema.ts.

Middleware stack details

Middleware	Package	Config
Security headers	`helmet` v8	CSP with per-request nonce; `reportOnly` in dev
Response compression	`compression`	gzip
Rate limiting	`express-rate-limit` v8	300 req / 15 min global; 10 req / 15 min on auth
Session auth	Custom (`server/auth.ts`)	Validates `X-Session-Id` header; scrypt password hashing; AES-256-GCM key storage
Request logging	`winston`	Structured JSON; 4 levels
Metrics	`server/metrics.ts`	In-memory route-level latency and request counts

AI engine

The AI system (server/ai.ts) is built on Google Genkit with support for both Claude (Anthropic) and Gemini (Google) models. Key characteristics:

SSE streaming — AI responses stream token-by-token to the client over a long-lived Server-Sent Events connection. The STREAM_TIMEOUT_MS environment variable controls the inactivity timeout (default 120 seconds).
82 tools — The AI has access to 82 registered tools organized across 11 modules under server/ai-tools/. Tools cover navigation, architecture operations, circuit design, component management, BOM operations, validation, exports, and project management.
Multi-model routing — The routing strategy is configurable per user (user, auto, quality, speed, cost) and stored in user_chat_settings.
Circuit AI — server/circuit-ai.ts handles circuit-specific AI endpoints with its own set of circuit manipulation tools.

Storage layer

server/storage.ts (1,598 lines) defines the IStorage interface — a single contract for all database operations — and DatabaseStorage, the PostgreSQL-backed implementation. An in-process LRU cache (server/cache.ts) sits in front of all reads, with prefix-based invalidation to ensure cache coherency when writes occur.All route handlers talk exclusively to IStorage, never to Drizzle directly. This allows the storage layer to be swapped or mocked in tests.

Export system

server/export/ contains 16 export modules, each implementing a specific output format:

Module	Output
`kicad-exporter.ts`	KiCad `.kicad_sch`, `.kicad_pcb`, `.kicad_pro`
`eagle-exporter.ts`	Eagle `.sch` / `.brd` XML
`gerber-generator.ts`	Gerber RS-274X layers
`drill-generator.ts`	Excellon drill file
`spice-exporter.ts`	SPICE netlist (`.cir`)
`netlist-generator.ts`	Netlist in SPICE, KiCad, or CSV
`bom-exporter.ts`	BOM CSV (generic, JLCPCB, Mouser, DigiKey)
`pick-place-generator.ts`	Pick-and-place CSV
`fzz-handler.ts`	Fritzing `.fzz` project
`pdf-generator.ts`	SVG/PDF view export
`pdf-report-generator.ts`	Full PDF design report
`fmea-generator.ts`	FMEA analysis CSV
`firmware-scaffold-generator.ts`	Arduino/PlatformIO scaffold code
`drc-gate.ts`	Pre-export DRC validation gate

Database architecture

All persistent state lives in PostgreSQL 14+, accessed exclusively through Drizzle ORM. The schema is defined in a single file — shared/schema.ts — that is imported by both the server (for queries) and the client (for TypeScript types).

Schema file

shared/schema.ts exports:

Drizzle table definitions — pgTable() calls for every table
Zod insert schemas — generated by drizzle-zod’s createInsertSchema(), used for request validation
TypeScript types — inferred from the Drizzle schema using $inferSelect and z.infer<>

This means a single source of truth drives database structure, API validation, and TypeScript typing simultaneously.

Connection

server/db.ts sets up a pg connection pool and initializes the Drizzle client. The pool size defaults vary by deployment profile and can be overridden with the DB_POOL_MAX environment variable.

Migration strategy

Environment	Command	Mechanism
Development	`npm run db:push`	`drizzle-kit push` — fast schema sync, no migration files
Production	`npm run db:migrate`	`drizzle-kit migrate` — applies versioned SQL files from `migrations/`

Migration history (from drizzle.config.ts):

0000 — Baseline: 19 original tables (2026-02-28)
0001 — CHECK constraints for enum-like text columns (2026-03-01)
0002 — Schema sync: 8 new tables + column additions (2026-03-08)

Soft deletes

The projects, architecture_nodes, architecture_edges, and bom_items tables use soft deletes via a deleted_at timestamp column. All read queries in DatabaseStorage filter with WHERE deleted_at IS NULL. Hard deletes are used for chat messages, history items, validation issues, and circuit tables.See Database Schema for a full table-by-table reference.

Shared code

The shared/ directory contains code that runs on both client and server:

File	Purpose
`shared/schema.ts`	Drizzle ORM schema (47 tables), Zod insert schemas, TypeScript types
`shared/component-types.ts`	Component editor type system — shapes, connectors, buses, DRC rules
`shared/drc-engine.ts`	Design Rule Check engine (runs client-side in real time)
`shared/drc-templates.ts`	Standard DRC rule templates
`shared/bom-diff.ts`	BOM snapshot comparison engine
`shared/netlist-diff.ts`	Netlist comparison and ECO engine
`shared/api-types.generated.ts`	Generated API type definitions (regenerate with `npm run types:generate`)

The @shared path alias (configured in vite.config.ts and tsconfig.json) lets both client and server code import from the shared directory with import { ... } from "@shared/schema" instead of relative paths.

Tech stack summary

Layer	Technology	Version
Frontend framework	React	19
Build tool	Vite	7
Server framework	Express	5
Runtime	Node.js	20+
Language	TypeScript	5.6
Database	PostgreSQL	14+
ORM	Drizzle ORM	0.45+
Server state	TanStack React Query	5
Client routing	Wouter	3
UI primitives	Radix UI + shadcn/ui	—
Canvas / diagrams	@xyflow/react (React Flow)	12
Styling	Tailwind CSS	v4
AI runtime	Google Genkit	1.30+
AI models	Claude (Anthropic), Gemini (Google)	—
Auth	scrypt + AES-256-GCM (custom)	—
Testing	Vitest	4
E2E testing	Playwright	1.58+
Desktop shell	Tauri	2

Setup & Architecture

API Reference

Contributing

ProtoPulse System Architecture

High-level overview

Request lifecycle

Frontend architecture

State management

Routing

UI layer

Key components

Context providers

Backend architecture

Entry point

Route organization

Middleware stack details

AI engine

Storage layer

Export system

Database architecture

Schema file

Connection

Migration strategy

Soft deletes

Shared code

Tech stack summary

Build docs developers (and LLMs) love

Setup & Architecture

API Reference

Contributing

Documentation Index

​High-level overview

​Request lifecycle

​Frontend architecture

​State management

​Routing

​UI layer

​Key components

​Context providers

​Backend architecture

​Entry point

​Route organization

​Middleware stack details

​AI engine

​Storage layer

​Export system

​Database architecture

​Schema file

​Connection

​Migration strategy

​Soft deletes

​Shared code

​Tech stack summary

Build docs developers (and LLMs) love

High-level overview

Request lifecycle

Frontend architecture

State management

Routing

UI layer

Key components

Context providers

Backend architecture

Entry point

Route organization

Middleware stack details

AI engine

Storage layer

Export system

Database architecture

Schema file

Connection

Migration strategy

Soft deletes

Shared code

Tech stack summary