project-89 argos-server .cursorrules file for TypeScript (stars: 2)

# Argos Server - Development Rules and Guidelines

## Project Overview
Argos Server is a Firebase Functions-based API server that handles fingerprinting, visit tracking, and pricing operations. The server is designed to be secure, scalable, and maintainable with a strong emphasis on authentication and data integrity.

## Repository Structure
The argos-server repository is organized with the Firebase Functions code contained within the `functions` directory at the repository root:

```
argos-server/           # Repository root
├── functions/          # Firebase Functions directory
│   ├── src/           # Source code directory
│   │   ├── constants/ # Global constants and configurations
│   │   ├── middleware/# Express middleware (auth, validation, etc.)
│   │   ├── routes/    # API route handlers
│   │   ├── services/  # Business logic and data operations
│   │   ├── types/     # TypeScript type definitions
│   │   ├── utils/     # Helper functions and utilities
│   │   └── test/      # Test files mirroring src structure
│   │       ├── endpoints/  # API endpoint tests
│   │       ├── setup/     # Test configuration and setup
│   │       └── utils/     # Test utilities
│   ├── package.json   # Node.js dependencies and scripts
│   └── tsconfig.json  # TypeScript configuration
└── README.md          # Repository documentation
```

## Development Guidelines

### 1. File Management
- **NEVER assume a file doesn't exist**
- Before creating new files:
  1. Search for existing files with similar names or purposes
  2. Review existing files for potential conflicts or overlap
  3. Document why a new file is needed if creating one
- When modifying files:
  1. Read and understand the entire file first
  2. Consider impacts on dependent files
  3. Maintain existing patterns and conventions

### 2. Development Process
1. **Incremental Development**
   - Work in small, testable increments
   - Complete and test one feature before moving to the next
   - Document completed work in DEVELOPMENT.md

2. **Testing**
   - Run type checking before executing any tests
   - Write tests before or alongside feature code
   - Ensure all tests pass before committing changes
   - Use dynamic API keys and fingerprints in tests
   - Clean up test data after each test suite

3. **Documentation**
   - Maintain DEVELOPMENT.md for tracking progress
   - Document all API endpoints and their requirements
   - Keep code comments current and meaningful
   - Update README.md with new features or changes

### 3. Server Architecture

#### Authentication
- API key-based authentication for protected endpoints
- Public endpoints limited to registration operations
- One API key per fingerprint
- API key usage tracking and validation

#### Data Management
- Firestore collections for:
  - Fingerprints
  - API Keys
  - Visits
  - Pricing Data
- Proper data validation and sanitization
- Ownership verification for all operations

#### Error Handling
- Consistent error response format
- Proper logging for debugging
- Graceful failure handling
- Rate limiting and abuse prevention

### 4. Best Practices
- Use TypeScript for type safety
- Run type checking before tests
- Follow ESLint and Prettier configurations
- Keep functions small and focused
- Use meaningful variable and function names
- Implement proper error handling
- Log important operations and errors
- Use environment variables for configuration

### 5. Security
- Validate all input data
- Protect sensitive endpoints
- Implement rate limiting
- Check ownership before operations
- Never expose internal errors to clients
- Use proper CORS settings

### 6. Performance
- Optimize database queries
- Implement caching where appropriate
- Monitor function execution times
- Keep payload sizes minimal
- Use batch operations when possible

## Development Workflow

1. **Planning**
   - Review existing codebase
   - Document intended changes
   - Identify affected components

2. **Implementation**
   - Make small, focused changes
   - Follow file management guidelines
   - Write/update tests
   - Document changes

3. **Testing**
   - Run type checking: `tsc --noEmit`
   - Run affected tests
   - Run full test suite
   - Fix any failures
   - Document test results

4. **Documentation**
   - Update DEVELOPMENT.md
   - Add API documentation if needed
   - Document any new patterns or requirements

5. **Review**
   - Self-review changes
   - Ensure all tests pass
   - Verify documentation is complete
   - Check for security implications

## Tracking Progress

Maintain a DEVELOPMENT.md file with:
```markdown
# Development Progress

## [Date] - [Feature/Change]
- [x] Implemented feature X
- [x] Added tests for feature X
- [x] All tests passing
- [ ] Next planned feature Y

## Issues and Solutions
- Problem: [Description]
- Solution: [Implementation details]