description: "StackTracker – General development & architecture rules for AI collaborators" globs:

"**/*" alwaysApply: true

StackTracker Cursor Rules

These rules apply to every file in the repository and are always injected into the AI's context. They encode our core conventions so that automated edits stay aligned with human expectations.

Core Principles

Plan → Act: Before making code changes, generate a short plan (bullet list, MECE). Revise it if the human asks, then implement.
Minimal disruption: Prefer additive edits; avoid large rewrites unless explicitly requested.
Context awareness: Read referenced files and reuse existing patterns. Do not introduce redundant libraries.

Front‑end Standards

React 18 + TypeScript, functional components, named exports.
TanStack Query for data, shadcn/ui + TailwindCSS for styling, Framer Motion for animations.
Keep components ≤200 LOC; split if larger.
Place UI in
```
/client/src/components
```
, pages in
```
/client/src/pages
```
.

Back‑end Standards

Express + TypeScript with ESM imports (
```
import x from 'y';
```
),
```
.js
```
extensions in compiled imports.
Reuse OpenAI wrapper in
```
/server/openai.ts
```
; never instantiate the SDK elsewhere.
All new endpoints must include input validation with Zod and integration tests.

Testing

Jest for all unit/integration tests.
New features must raise global coverage (target ≥ 80 %).
Tests live in
```
server/tests
```
and use the helpers in
```
test/setup.ts
```
.

Database & Migrations

Drizzle ORM over Postgres (Neon for prod, local for dev).
Each migration: single concern, file pattern
```
YYYYMMDD_<description>.ts
```
.
Use
```
npx tsx
```
to run migrations; clean up connections with
```
await client.end()
```
in
```
finally
```
.
Rollback logic is mandatory.

Drizzle Type Conventions

Table definitions use camelCase (e.g.,
```
labResults
```
,
```
biomarkerResults
```
).
Type definitions use PascalCase with prefixes:
- ```
Select
```
  prefix for types used when selecting records (e.g.,
```
SelectLabResult
```
  )
- ```
Insert
```
  prefix for types used when inserting records (e.g.,
```
InsertBiomarkerResult
```
  )

Import types explicitly:

import type { SelectLabResult, InsertBiomarkerResult } from '../../db/schema'

Never use pluralized table names as types (e.g., avoid
```
LabResults
```
, use
```
SelectLabResult
```
instead)

AI / LLM Integration

Keep requests within token and rate limits; prefer GPT‑4o‑mini unless overridden.
Strip PII before sending user data.
Update context–building tests when adding new sources.

Security

Never commit
```
.env
```
; update
```
.env.example
```
instead.
Use Helmet and CORS middleware defaults.
All secrets accessed via
```
process.env
```
.

Style Guide

TypeScript strict mode must pass.
Use Prettier default config; 100‑char line width.
CamelCase for variables, PascalCase for components, snake_case for SQL identifiers.

Example — Adding a biomarker feature

Write migration and update Drizzle schema.
Add service & route in
```
/server
```
.
Create React chart component in
```
/components/charts
```
.
Add hook with TanStack Query.
Write unit + integration tests.
Document in
```
docs/biomarkers.md
```
.

@development.md @db/migrations/migration_template.ts @client/src/components/component_template.tsx

Core Principles

Plan → Act: Before making code changes, generate a short plan (bullet list, MECE). Revise it if the human asks, then implement.

Minimal disruption: Prefer additive edits; avoid large rewrites unless explicitly requested.

Context awareness: Read referenced files and reuse existing patterns. Do not introduce redundant libraries.

Database & Migrations

Drizzle ORM over Postgres (Neon for prod, local for dev).

Each migration: single concern, file pattern

YYYYMMDD_<description>.ts

Use

npx tsx

to run migrations; clean up connections with

await client.end()

finally

Rollback logic is mandatory.

Table definitions use camelCase (e.g.,

labResults

biomarkerResults

Type definitions use PascalCase with prefixes:

```
Select
```
prefix for types used when selecting records (e.g.,
```
SelectLabResult
```
)
```
Insert
```
prefix for types used when inserting records (e.g.,
```
InsertBiomarkerResult
```
)

Import types explicitly:

import type { SelectLabResult, InsertBiomarkerResult } from '../../db/schema'

Never use pluralized table names as types (e.g., avoid

LabResults

, use

SelectLabResult

instead)

Example — Adding a biomarker feature

Write migration and update Drizzle schema.

Add service & route in

/server

Create React chart component in

/components/charts

Add hook with TanStack Query.

Write unit + integration tests.

Document in

docs/biomarkers.md

@development.md @db/migrations/migration_template.ts @client/src/components/component_template.tsx

description: "StackTracker – General development & architecture rules for AI collaborators"

StackTracker Cursor Rules

Core Principles

Front‑end Standards

Back‑end Standards

Testing

Database & Migrations

Drizzle Type Conventions

AI / LLM Integration

Security

Style Guide

Example — Adding a biomarker feature

Related Skills

Markdown Converter

Nano Banana Pro

1password

StackTracker Cursor Rules

Core Principles

Front‑end Standards

Back‑end Standards

Testing

Database & Migrations

Drizzle Type Conventions

AI / LLM Integration

Security

Style Guide

Example — Adding a biomarker feature