.clinerules

# QDash Project Rules

## Overview
QDash is a platform for managing qubit calibration workflows. These rules ensure consistent development practices across the project's components:
- UI: Next-based frontend for workflow management
- Server: FastAPI backend for request handling and database communication
- QCFlow: Prefect-based workflow engine for qubit calibration

## Project Structure
- backend/: Python backend code
  - server/: FastAPI server implementation
  - qcflow/: Prefect-based workflow engine
  - datamodel/: Core domain models
  - neodbmodel/: Database models for mongodb
  - tests/: Test files
- ui/: Next.js frontend code
  - src/app/: Application components and pages
  - src/client/: Auto-generated API client (orval)
  - src/lib/: Shared utilities and hooks
  - src/schemas/: TypeScript type definitions
- docs/: Project documentation and architecture diagrams
- scripts/: Development and deployment scripts
- init/: Database and system initialization code

## Coding Standards

### Python (Backend)
1. FastAPI routes should not use async by default
2. Use type hints for all function parameters and return values and pydantic models for request and response bodies
3. Follow PEP 8 style guide
4. Class naming:
   - Models: PascalCase (e.g., QubitCalibration)
   - Routers: snake_case with _router suffix (e.g., calibration_router)
5. Function naming:
   - API endpoints: snake_case (e.g., get_calibration_status)
   - Internal methods: snake_case
6. Variable naming:
   - Constants: UPPER_CASE
   - Variables: snake_case
7. Comments must be in English
8. Workflow specific:
   - Use Prefect for workflow definitions
   - Implement proper execution locking
   - Generate unique execution_id for each run

### TypeScript (Frontend)
1. Use functional components with hooks
2. Follow ESLint configuration
3. Naming conventions:
   - Components: PascalCase
   - Hooks: camelCase with use prefix
   - Interfaces: PascalCase with I prefix
   - Types: PascalCase
4. File organization:
   - One component per file
   - Index files for exports
5. State management:
   - Use React Query for server state
   - Use React Context for global state
6. Comments must be in English
7. API client:
   - Use orval-generated clients
   - Keep API types in sync with backend

## Database Access Patterns
1. Always use repository pattern
2. Define clear data models
3. Use appropriate database for the use case:
   - MongoDB: For flexible schema data (e.g., calibration results)
4. Include proper error handling
5. Use transactions when necessary
6. Implement proper locking mechanisms for calibration workflows

## API Design
1. Base URL structure: /api/v1/
2. Resource naming:
   - Use plural nouns
   - Use kebab-case
3. HTTP methods:
   - GET: Retrieve data
   - POST: Create new resource
   - PUT: Update existing resource
   - DELETE: Remove resource
4. Response format:
   - Success: { data: T, message?: string }
   - Error: { error: string, details?: any }
5. OpenAPI:
   - Keep schema up to date
   - Use for client code generation
   - Document all endpoints

# ## Testing
# 1. Unit tests required for:
#    - All API endpoints
#    - Business logic functions
#    - Utility functions
#    - Workflow definitions
# 2. Integration tests for:
#    - Database operations
#    - API flows
#    - Complete calibration workflows
# 3. Test file naming:
#    - Unit tests: *_test.py
#    - Integration tests: *_integration_test.py
# 4. Use pytest for Python tests
# 5. Use Jest for TypeScript tests
# 6. Test coverage requirements:
#    - Backend: Minimum 80%
#    - Frontend: Minimum 70%

## Documentation
1. All public functions must have docstrings
2. API endpoints must be documented with OpenAPI
3. README files must exist in major directories
4. Architecture documentation:
   - Keep diagrams up to date
   - Document workflow patterns
   - Include calibration flow explanations
5. Document database schema changes
6. Maintain development setup guides

## Git Workflow
1. Branch Strategy:
   - main: Release branch
   - develop: Latest development code
   - feature/*: New features (from develop)
   - bugfix/*: Bug fixes (from develop)
   - hotfix/*: Urgent fixes (from develop)

2. Commit Messages:
   - Follow Conventional Commits specification
   - Use provided .gitmessage template
   - Prefixes:
     - feat: New features
     - fix: Bug fixes
     - docs: Documentation changes
     - style: Code style changes
     - refactor: Code refactoring
     - test: Test updates
     - ci: CI configuration changes
     - chore: Maintenance tasks

# 3. Pull Request Requirements:
#    - Branch is up to date with develop
#    - All tests pass
#    - Linting passes
#    - Documentation updated
#    - Architecture diagrams updated (if needed)
#    - Peer review completed
#    - Proper labels applied (based on commit prefixes)

# ## Error Handling
# 1. Use custom exception classes
# 2. Log errors with appropriate levels
# 3. Return consistent error responses
# 4. Include stack traces in development
# 5. Workflow specific:
#    - Handle calibration failures gracefully
#    - Implement proper cleanup on errors
#    - Log detailed workflow execution errors

# ## Performance Guidelines
# 1. Database optimization:
#    - Use appropriate indexes
#    - Optimize queries
#    - Implement caching where beneficial
# 2. Frontend optimization:
#    - Lazy load components
#    - Minimize bundle size
#    - Implement proper data pagination
# 3. Workflow optimization:
#    - Efficient task scheduling
#    - Resource management
#    - Parallel execution where possible

# ## Security
# 1. Input validation on all API endpoints
# 2. Sanitize database queries
# 3. Implement proper authentication
# 4. Use HTTPS in production
# 5. Follow OWASP guidelines
# 6. Secure workflow execution:
#    - Validate calibration parameters
#    - Implement access controls
#    - Protect sensitive measurement data

# ## Monitoring
# 1. Log important operations:
#    - API requests
#    - Workflow executions
#    - Calibration results
# 2. Track performance:
#    - API response times
#    - Database query times
#    - Workflow execution times
# 3. Monitor system health:
#    - Database connections
#    - Workflow engine status
#    - Resource utilization
# 4. Set up alerts for:
#    - Workflow failures
#    - System errors
#    - Performance degradation