stones/RULES.md

Project Rules and Guidelines

Code Style and Structure

TypeScript/JavaScript

• Use TypeScript for all frontend and backend code
• Follow functional programming patterns; avoid classes
• Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
• Use ESLint and Prettier for code formatting

Python

• Follow PEP 8 style guide
• Use type hints where possible
• Document functions with docstrings
• Use virtual environments for dependency management

File Organization

Frontend

• Place components in src/components with kebab-case filenames
• Group components by type or feature
• Use the Next.js App Router structure in src/app
• Keep page components minimal, delegating to imported components

Backend

• Organize server code in src/server
• Separate routes, controllers, and services
• Use middleware for cross-cutting concerns

Data Collection Scripts

• Place scripts in the scripts directory
• Organize by data source type
• Include documentation for each script
• Implement error handling and logging

Database

• Use Prisma for database schema and migrations
• Document schema changes
• Include seed data for development
• Implement proper indexing for performance

Security

• Never commit sensitive information (API keys, credentials)
• Use environment variables for configuration
• Implement proper authentication and authorization
• Validate and sanitize all user inputs

Git Workflow

• Use feature branches
• Write descriptive commit messages
• Review code before merging
• Keep commits focused and atomic

File Extensions

• .tsx - TypeScript React components
• .ts - TypeScript files
• .js - JavaScript files (avoid if possible)
• .py - Python scripts
• .prisma - Prisma schema
• .env - Environment variables (not committed)
• .env.example - Example environment variables (committed)
• .md - Markdown documentation
• .json - Configuration files
• .yaml or .yml - Docker and other configuration
• .css - CSS files (minimal use with Tailwind)
• .sql - SQL scripts if needed

Dependencies

• Minimize dependencies to reduce security risks
• Document purpose of each dependency
• Keep dependencies updated
• Use exact versions in package.json