StackTracker Development Rules
Comprehensive development and architecture guidelines for AI collaborators working on StackTracker, a qualitative supplement tracker. These rules ensure consistent code patterns, proper planning, and alignment with project conventions.
Core Principles
Planning Before Implementation
**Always generate a plan before making code changes**: Create a short bullet list using MECE (Mutually Exclusive, Collectively Exhaustive) principles**Revise the plan if requested**: Allow the human to review and adjust before implementation**Then implement**: Execute the plan only after approval or confirmationCode Change Philosophy
**Prefer additive edits**: Add new functionality without disrupting existing code**Avoid large rewrites**: Only perform substantial refactors when explicitly requested**Maintain backward compatibility**: Preserve existing interfaces and behaviors unless specifically asked to change themContext Awareness
**Read referenced files first**: Always examine existing code before making changes**Reuse existing patterns**: Follow established conventions and code structures**Avoid redundant libraries**: Don't introduce new dependencies when existing ones can be usedFront-end Standards
Technology Stack
**React 18** with TypeScript**Functional components only** with named exports**TanStack Query** (React Query) for server state management**shadcn/ui** + **TailwindCSS** for styling**Framer Motion** for animationsComponent Guidelines
**Maximum component size**: 200 lines of code**Split larger components**: Break into smaller, focused components when exceeding limit**File organization**: - UI components in `/client/src/components`
- Page components in `/client/src/pages`
Code Style
Use functional components with hooksNamed exports (avoid default exports)TypeScript strict mode must passPascalCase for component namesBack-end Standards
Technology Stack
**Express** with TypeScript**ESM imports** syntax: `import x from 'y';`**Compiled imports** must include `.js` extensionsAPI Conventions
**Input validation**: All endpoints must use Zod for request validation**Integration tests**: Every new endpoint requires integration tests**OpenAI integration**: Reuse the wrapper in `/server/openai.ts` — never instantiate the SDK elsewhere**Error handling**: Consistent error responses with proper HTTP status codesCode Style
CamelCase for variables and functionsPascalCase for classes and typesAsync/await for asynchronous operationsDatabase & Migrations
ORM & Database
**Drizzle ORM** over PostgreSQL**Neon** for production, local Postgres for development**Migrations directory**: `db/migrations/`Migration Guidelines
**Single concern**: Each migration should address one specific change**File naming**: `YYYYMMDD_<description>.ts` (e.g., `20240115_add_biomarker_table.ts`)**Execution**: Use `npx tsx` to run migrations**Cleanup**: Always include `await client.end()` in `finally` blocks**Rollback logic**: Mandatory for all migrationsDrizzle Type Conventions
**Table definitions**: Use camelCase (e.g., `labResults`, `biomarkerResults`)**Type definitions**: Use PascalCase with prefixes: - `Select` prefix for selecting records (e.g., `SelectLabResult`)
- `Insert` prefix for inserting records (e.g., `InsertBiomarkerResult`)
**Import types explicitly**: `import type { SelectLabResult, InsertBiomarkerResult } from '../../db/schema'`**Never use pluralized table names as types**: Avoid `LabResults`, use `SelectLabResult` insteadTesting Standards
Test Framework
**Jest** for all unit and integration tests**Test location**: `server/tests`**Test helpers**: Use utilities in `test/setup.ts`Testing Requirements
**New features must raise global coverage**: Target ≥ 80% code coverage**Unit tests** for business logic and utilities**Integration tests** for API endpoints**Test naming**: Descriptive test names that explain the scenarioAI / LLM Integration
Usage Guidelines
**Stay within limits**: Respect token and rate limits**Model selection**: Prefer GPT-4o-mini unless higher capability is explicitly required**PII protection**: Strip personally identifiable information before sending user data to AI services**Context building**: Update context-building tests when adding new data sourcesSecurity Standards
Environment & Secrets
**Never commit `.env` files**: Use `.env.example` for documentation**Update `.env.example`**: When adding new environment variables**Access secrets via `process.env`**: Never hardcode credentialsMiddleware & Protection
**Helmet**: Use default configuration for security headers**CORS**: Apply CORS middleware with appropriate origin restrictions**Input validation**: Always validate and sanitize user inputStyle Guide
TypeScript
**Strict mode**: All code must pass TypeScript strict mode checks**Explicit types**: Prefer explicit type annotations over inference where it improves clarity**No `any`**: Avoid the `any` type; use `unknown` or proper typingFormatting
**Prettier**: Use default Prettier configuration**Line width**: 100 characters maximum**Consistent formatting**: Run Prettier before committingNaming Conventions
**camelCase**: Variables, functions, methods**PascalCase**: Components, classes, types, interfaces**snake_case**: SQL identifiers (columns, tables)**UPPER_SNAKE_CASE**: Constants and environment variablesExample: Adding a Biomarker Feature
Follow this workflow when adding a new feature like biomarker tracking:
1. **Database**: Write migration and update Drizzle schema
2. **Backend**: Add service layer and API route in `/server`
3. **Frontend Component**: Create React chart component in `/components/charts`
4. **Data Fetching**: Add custom hook with TanStack Query
5. **Testing**: Write unit tests and integration tests
6. **Documentation**: Document in `docs/biomarkers.md`
Referenced Files
`@development.md` — Extended development documentation`@db/migrations/migration_template.ts` — Migration file template`@client/src/components/component_template.tsx` — Component template