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 follows a vertical-slice development model — every feature is implemented top-to-bottom across all layers before it is considered done. This keeps each change self-contained, testable end-to-end, and easy to review. The slice for any feature flows in a fixed order: 
Schema  →  Storage  →  API Route  →  React Query  →  UI Component  →  Test

​
Prerequisites

Before contributing, make sure you have:
  • Node.js 20+ — the dev server and build scripts require it
  • PostgreSQL 14+ — the app stores all data in PostgreSQL via Drizzle ORM
  • Familiarity with TypeScript — the entire codebase (client, server, shared) is TypeScript 5.6 with strict: true
  • Familiarity with React — the frontend is React 19 with TanStack React Query for all server state
Both npm run dev and the Vite dev server run on port 5000. The Express backend serves the Vite HMR proxy, so you only need to open one URL: http://localhost:5000. There is no separate client port to configure.

​
Development workflow

1

Fork and clone the repository

Fork the repository on GitHub, then clone your fork locally:
git clone https://github.com/<your-username>/ProtoPulse.git
cd ProtoPulse
2

Create a feature branch

Always work from a dedicated branch. Use a descriptive name that reflects the change:
git checkout -b feat/add-spice-export-options
3

Install dependencies and set up the database

Install all npm dependencies, then push the Drizzle schema to your PostgreSQL instance:
npm install
Create a .env file with your database connection string:
DATABASE_URL=postgresql://user:pass@localhost:5432/protopulse
NODE_ENV=development
Push the schema:
npm run db:push
Start the development server:
npm run dev
The app will be available at http://localhost:5000 with Vite HMR active.
4

Make changes following the vertical slice model

Implement your feature in the following order — do not skip layers:
  1. shared/schema.ts — Add or modify the Drizzle ORM table definition and Zod insert schema
  2. server/storage.ts — Add methods to IStorage and implement them in DatabaseStorage
  3. server/routes/ — Add the API route with asyncHandler, Zod body validation, and IStorage calls
  4. client/src/lib/project-context.tsx — Add the React Query useQuery or useMutation hook
  5. client/src/components/ — Build the UI component, adding data-testid to every interactive element
5

Write tests — npm test must pass with zero failures

Every new feature requires tests. Add them in the __tests__/ subdirectory co-located with the source file you changed. Server tests live in server/__tests__/, client tests live next to the source under client/src/.Run the full test suite to confirm nothing is broken:
npm test
If any test fails, fix the code — not the test. Tests reveal bugs.
6

Run type checking — npm run check must pass with zero errors

TypeScript strict mode is enforced with no exceptions. After your changes, verify the type check is clean:
npm run check
Never dismiss a pre-existing error as “not your fault” — if it was already there, it is still a bug. Fix it or open a separate issue.
7

Run linting and formatting

ESLint enforces strict TypeScript rules including no-explicit-any and consistent import type usage. Prettier enforces formatting. Run both before committing:
npx eslint .
npx prettier --write .
ESLint should report zero errors. Prettier rewrites files in place — commit the formatted output.
8

Submit a pull request

Push your branch and open a pull request against main. In the PR description, explain:
  • What the change does and why
  • Which vertical slice layers were touched
  • How you tested it
A PR that passes all checks (zero type errors, zero test failures, zero lint errors) will be reviewed promptly.

​
Test requirements

All contributions must meet these testing standards before a PR can be merged:
RequirementCommandStandard
All tests passnpm testZero failures across all 54 test files
Type check passesnpm run checkZero TypeScript errors
New features have tests—Tests added in the appropriate __tests__/ directory
Specific rules:
  • Add data-testid to every interactive UI element (buttons, inputs, dropdowns, canvas targets). This is an explicit convention, not optional.
  • Use @testing-library/react for component behavior tests — test what users see and do, not implementation details.
  • Use descriptive test names in the pattern: "should [action] when [condition]".
  • Run only the tests relevant to your change during development: npx vitest run path/to/file.test.ts.

​
PR requirements

A pull request will not be merged unless it satisfies all of the following:
  • Zero TypeScript errors — npm run check is clean
  • Zero test failures — npm test is clean
  • Zod validation on every request body — use schema.safeParse(req.body) in every route handler that accepts a body; Zod schemas live in shared/schema.ts
  • ErrorBoundary per view — any new view component added to ProjectWorkspace must be wrapped in an ErrorBoundary

​
What not to do

Never hard-delete rows from projects, architecture_nodes, architecture_edges, or bom_items. These tables use soft deletes — set the deletedAt timestamp column instead of issuing a DELETE SQL statement. This preserves data for audit trails and admin recovery. Hard deletes are only appropriate for tables like validation_issues and history_items that do not carry deletedAt.
  • No import X from '...' for type-only imports. The ESLint import-x plugin enforces import type for all imports that are used only as types. A violation will fail the lint step.
  • No as any. Use proper type narrowing, discriminated unions, or generics instead. @typescript-eslint/no-explicit-any is configured as an error.
  • No UUID generation with Date.now(). Always use crypto.randomUUID().
  • No direct database queries in route handlers. All data access goes through IStorage — never import the Drizzle db object directly in a route file.

Build docs developers (and LLMs) love

Get started for freeTalk to us