StackTracker Development Rules

Comprehensive development and architecture guidelines for AI collaborators working on StackTracker, a code search and analysis platform that integrates with CSV databases and GitHub Actions.

Core Principles

Follow these fundamental principles for all code changes:

1. **Plan → Act**: Before making any code changes, generate a short, MECE (Mutually Exclusive, Collectively Exhaustive) plan as a bullet list. Wait for human approval or revision before implementing.

2. **Minimal Disruption**: Prefer additive edits over large rewrites. Only perform major refactoring when explicitly requested.

3. **Context Awareness**: Always read referenced files first and reuse existing patterns. Never introduce redundant libraries or duplicate functionality.

Front-End Standards

Technology Stack

Component Guidelines

Example Component Structure

```typescript

// client/src/components/MyComponent.tsx

import type { FC } from 'react';

interface MyComponentProps {

data: string;

}

export const MyComponent: FC<MyComponentProps> = ({ data }) => {

return <div>{data}</div>;

};

```

Back-End Standards

Technology Stack

API Guidelines

- Input validation using Zod schemas

- Integration tests

- Error handling middleware

Example Route Structure

```typescript

// server/routes/myRoute.ts

import { Router } from 'express';

import { z } from 'zod';

const router = Router();

const inputSchema = z.object({

field: z.string()

});

router.post('/endpoint', async (req, res) => {

const validated = inputSchema.parse(req.body);

// implementation

});

export { router };

```

Database & Migrations

Drizzle ORM Conventions

Migration Guidelines

Example Migration

```typescript

// db/migrations/20240115_add_biomarkers.ts

import { sql } from 'drizzle-orm';

export async function up(db) {

// migration logic

}

export async function down(db) {

// rollback logic

}

```

Testing Requirements

Testing Stack

Coverage Requirements

AI/LLM Integration

When integrating with language models:

1. **Token Management**: Keep requests within token and rate limits

2. **Model Selection**: Prefer GPT-4o-mini unless explicitly overridden

3. **Privacy**: Strip PII before sending user data to any LLM

4. **Testing**: Update context-building tests when adding new data sources

Security Guidelines

1. **Secrets Management**

- Never commit `.env` files

- Update `.env.example` when adding new environment variables

- Access all secrets via `process.env`

2. **Middleware**

- Use Helmet middleware for security headers

- Configure CORS appropriately

- Implement rate limiting where necessary

Code Style

TypeScript

Formatting

Naming Conventions

Example Workflow: Adding a Biomarker Feature

Follow this step-by-step process when adding new features:

1. **Database**: Write migration and update Drizzle schema in `/db/schema.ts`

2. **Backend**: Add service layer in `/server/services` and routes in `/server/routes`

3. **Frontend**: Create React chart component in `/client/src/components/charts`

4. **Data Layer**: Add TanStack Query hook in `/client/src/hooks`

5. **Testing**: Write unit tests and integration tests

6. **Documentation**: Document in appropriate file under `/docs`

File Organization

```

/client

/src

/components # Reusable UI components

/pages # Page-level components

/hooks # Custom React hooks

/lib # Utilities and helpers

/server

/routes # Express route handlers

/services # Business logic

/tests # Test files

openai.ts # OpenAI wrapper (reuse this!)

/db

/migrations # Database migrations

schema.ts # Drizzle schema definitions

```

Before Submitting Changes

Reference Files

When working on StackTracker, reference these files for templates and patterns: