# Technical Preferences for VC-SYS Projects

This document defines the technical preferences and standards that should be applied across VC-SYS projects. Used by QA Agent and UX Expert to ensure consistency and quality.

## Code Quality Standards

### General Principles
- **Clean Code**: Follow Robert Martin's Clean Code principles
- **SOLID Principles**: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
- **DRY**: Don't Repeat Yourself - abstract common functionality
- **KISS**: Keep It Simple, Stupid - prefer simplicity over complexity
- **YAGNI**: You Aren't Gonna Need It - implement only current requirements

### Code Organization
- **File Structure**: Logical organization with clear separation of concerns
- **Naming Conventions**: Clear, descriptive names for variables, functions, classes
- **Function Size**: Functions should do one thing and be < 20 lines when possible
- **Class Design**: Single responsibility with clear interfaces

## Frontend Development Standards

### Framework Preferences
**React/Next.js Projects:**
- Use functional components with hooks over class components
- Prefer TypeScript for type safety
- Use Next.js App Router for new projects
- Implement proper error boundaries

**Vue Projects:**
- Use Composition API over Options API
- Prefer TypeScript when possible
- Follow Vue 3 best practices
- Use Pinia for state management

**Angular Projects:**
- Use standalone components where possible
- Follow Angular style guide strictly
- Implement proper OnPush change detection
- Use Angular services for business logic

### CSS and Styling
**Preferred CSS Frameworks:**
1. **Tailwind CSS** - For utility-first styling
2. **CSS Modules** - For component-scoped styles
3. **Styled Components** - For React projects with dynamic styling

**CSS Best Practices:**
- Mobile-first responsive design
- Use CSS custom properties for theming
- Follow BEM methodology when not using utility classes
- Optimize for Core Web Vitals

### Component Design
- **Atomic Design**: Follow atomic design principles (atoms, molecules, organisms)
- **Reusability**: Create reusable components with clear props interfaces
- **Accessibility**: WCAG 2.1 AA compliance minimum
- **Performance**: Lazy load components when appropriate

## Backend Development Standards

### API Design
**RESTful APIs:**
- Follow REST principles consistently
- Use proper HTTP status codes
- Implement proper error handling
- Version APIs appropriately (/v1/, /v2/)

**GraphQL APIs:**
- Design schema-first approach
- Implement proper error handling
- Use DataLoader for efficient queries
- Implement proper authentication/authorization

**Database Design:**
- Normalize data structure appropriately
- Use proper indexing strategies
- Implement database migrations
- Follow security best practices (never store plain text passwords)

### Authentication and Security
- **JWT Tokens**: Use short-lived access tokens with refresh tokens
- **Password Hashing**: Use bcrypt or Argon2 for password hashing
- **Input Validation**: Validate all inputs server-side
- **HTTPS**: Always use HTTPS in production
- **CORS**: Configure CORS appropriately
- **Rate Limiting**: Implement rate limiting on APIs

## Testing Standards

### Testing Pyramid
1. **Unit Tests**: 70% - Test individual functions and components
2. **Integration Tests**: 20% - Test component interactions
3. **E2E Tests**: 10% - Test complete user workflows

### Testing Frameworks
**JavaScript/TypeScript:**
- **Jest**: For unit and integration testing
- **React Testing Library**: For React component testing
- **Playwright**: For E2E testing
- **Vitest**: Alternative to Jest for Vite projects

**Python:**
- **pytest**: For unit and integration testing
- **unittest**: Built-in testing framework
- **Selenium**: For E2E testing

### Testing Best Practices
- Write tests before or alongside code (TDD/TFD)
- Test behavior, not implementation
- Use descriptive test names
- Mock external dependencies appropriately
- Aim for high test coverage but prioritize critical paths

## Performance Standards

### Frontend Performance
**Core Web Vitals Targets:**
- **LCP (Largest Contentful Paint)**: < 2.5 seconds
- **FID (First Input Delay)**: < 100 milliseconds
- **CLS (Cumulative Layout Shift)**: < 0.1

**Additional Metrics:**
- **First Contentful Paint**: < 1.5 seconds
- **Time to Interactive**: < 3.5 seconds
- **Bundle Size**: Initial < 500KB, Total < 2MB

### Backend Performance
- **API Response Time**: < 200ms for simple queries
- **Database Query Time**: < 100ms for most queries
- **Memory Usage**: Monitor and optimize memory consumption
- **CPU Usage**: Keep CPU usage under 70% during normal operations

## Code Review Standards

### Review Checklist
- [ ] Code follows established patterns and conventions
- [ ] Security considerations are addressed
- [ ] Performance implications are considered
- [ ] Tests are included and pass
- [ ] Documentation is updated if needed
- [ ] Breaking changes are properly communicated

### Review Process
1. **Self Review**: Author reviews their own code first
2. **Peer Review**: At least one other developer reviews
3. **QA Review**: QA agent reviews for quality standards
4. **Security Review**: Security considerations verified

## Deployment and DevOps

### CI/CD Pipeline
- **Automated Testing**: All tests run on every commit
- **Code Quality Gates**: Linting, type checking, security scans
- **Staging Deployment**: Deploy to staging environment for testing
- **Production Deployment**: Automated deployment with rollback capability

### Environment Management
- **Development**: Local development environment
- **Staging**: Production-like environment for testing
- **Production**: Live environment with monitoring and alerting
- **Configuration**: Use environment variables for configuration

### Monitoring and Logging
- **Application Monitoring**: Track application performance and errors
- **Infrastructure Monitoring**: Monitor server resources and health
- **Logging**: Structured logging with appropriate log levels
- **Alerting**: Set up alerts for critical issues

## Documentation Standards

### Code Documentation
- **README**: Clear setup and usage instructions
- **API Documentation**: OpenAPI/Swagger for REST APIs
- **Code Comments**: Explain why, not what
- **Architecture Docs**: High-level system design documentation

### User Documentation
- **User Guides**: Step-by-step instructions for end users
- **Developer Guides**: Setup and contribution guidelines
- **Troubleshooting**: Common issues and solutions
- **Changelog**: Keep track of changes and releases

## VC-SYS Specific Preferences

### Agent Integration
- **Story-Driven Development**: All work should be driven by clear user stories
- **AI-Friendly Documentation**: Write documentation that AI agents can understand and use
- **Template-Based Consistency**: Use templates for consistent structure
- **Quality Gates**: Implement checkpoints for quality assurance

### Founder-Friendly Approach
- **Non-Technical Language**: Use clear, jargon-free explanations
- **Visual Documentation**: Include diagrams and visual aids where helpful
- **Decision Rationale**: Explain why technical decisions were made
- **Business Impact**: Connect technical choices to business outcomes

## Continuous Improvement

### Learning and Adaptation
- Regular review and update of technical preferences
- Adopt new best practices and technologies when appropriate
- Share learnings across projects and teams
- Measure and improve development velocity and quality

### Feedback Integration
- Collect feedback from developers, QA, and end users
- Iterate on standards based on real-world experience
- Balance consistency with flexibility for special cases
- Document exceptions and their rationale