Comprehensive development and architecture guidelines for StackTracker - a code search and analysis platform with React/TypeScript frontend and Express backend
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.
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.
```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>;
};
```
- Input validation using Zod schemas
- Integration tests
- Error handling middleware
```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 };
```
```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
}
```
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
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
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`
```
/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
```
When working on StackTracker, reference these files for templates and patterns:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/stacktracker-development-rules-4zsoaw/raw