diff --git a/.windsurf/rules/README.md b/.windsurf/rules/README.md new file mode 100644 index 000000000..94725cc28 --- /dev/null +++ b/.windsurf/rules/README.md @@ -0,0 +1,51 @@ +# Zapp.ie Rules + +This directory contains rules and guidelines for the Zapp.ie project. These rules help maintain consistency and quality across the codebase. + +## Available Rules + +- [Code Style](./code-style.md) +- [Testing](./testing.md) +- [Security](./security.md) +- [Performance](./performance.md) +- [Documentation](./documentation.md) + +## Adding New Rules + +To add a new rule: +1. Create a new markdown file in this directory +2. Document the rule clearly with examples +3. Update the README.md with a link to the new rule +4. Add any necessary configuration files + +## Rule Categories + +### Code Style +- Formatting +- Naming conventions +- Code organization +- Best practices + +### Testing +- Test coverage requirements +- Test naming conventions +- Mocking strategies +- Performance testing + +### Security +- Authentication/Authorization +- Data validation +- API security +- Environment security + +### Performance +- Response time targets +- Memory usage limits +- Caching strategies +- Database optimization + +### Documentation +- Code comments +- API documentation +- User documentation +- Change logs diff --git a/.windsurf/rules/code-style.md b/.windsurf/rules/code-style.md new file mode 100644 index 000000000..7f99e9799 --- /dev/null +++ b/.windsurf/rules/code-style.md @@ -0,0 +1,70 @@ +--- +trigger: manual +--- + +# Code Style Rules + +## General Guidelines + +-We prefer simple, elegant and concise coding solutions. +-We generally prefer Microsoft solutions and open-source solutions. +-We use kebab case for file and directory names. +-We use PascalCase for class names and camelCase for variables. + +### File Structure +- Use consistent file extensions (.tsx for TypeScript React components) +- Place related files in logical directories +- Keep files under 400 lines + +### Naming Conventions +- Components: PascalCase (e.g., UserProfile) +- Functions: camelCase (e.g., getUserProfile) +- Constants: UPPER_SNAKE_CASE (e.g., API_ENDPOINT) +- Variables: camelCase (e.g., userProfile) + +### React Components +- Use functional components with hooks +- Export components as default +- Use proper prop types +- Keep components pure and reusable + +### TypeScript +- Use strict mode +- Avoid any type +- Use interfaces for complex types +- Use enums for fixed value sets + +### Formatting +- 2 spaces indentation +- Single quotes +- Trailing commas +- Maximum line length: 80 characters + +### Imports +- Group related imports +- Alphabetize imports within groups +- Use named exports when possible + +### Error Handling +- Always handle API errors +- Use proper error boundaries +- Log errors appropriately +- Provide user-friendly error messages + +### Performance +- Memoize expensive computations +- Use proper component optimization +- Avoid unnecessary re-renders +- Implement proper cleanup + +### Testing +- Write unit tests for components +- Test edge cases +- Mock external dependencies +- Keep tests independent + +### Documentation +- Document complex logic +- Add JSDoc comments for public APIs +- Keep READMEs up to date +- Document state management diff --git a/.windsurf/rules/documentation.md b/.windsurf/rules/documentation.md new file mode 100644 index 000000000..863b2c90e --- /dev/null +++ b/.windsurf/rules/documentation.md @@ -0,0 +1,10 @@ +--- +trigger: manual +--- + +- For our methodology and backlog structure, refer to [T-Minus-15](https://github.com/BenGWeeks/T-Minus-15). +- Refer to requirements, if they exist, in /docs/requirements.yaml. +- Refer to personas, if they exist, in /docs/personas.yaml. +- Refer to solution design, if they exist, in /docs/solution-design.md. +- Refer to test strategy, if they exist, in /docs/test-strategy.md. +- Refer to data model, if they exist, in /docs/data-model.md. \ No newline at end of file diff --git a/.windsurf/rules/frameworks.md b/.windsurf/rules/frameworks.md new file mode 100644 index 000000000..d3866694c --- /dev/null +++ b/.windsurf/rules/frameworks.md @@ -0,0 +1,8 @@ +--- +trigger: manual +--- + +- Our packet manager preference is npm (not pnpm). +- My preferred frameworks are React, TypeScript, and Tailwind. +- We generally prefer Microsoft solutions and open-source solutions. +- We use Playwright to generate automated scripts. \ No newline at end of file diff --git a/.windsurf/rules/performance.md b/.windsurf/rules/performance.md new file mode 100644 index 000000000..a00d0deb1 --- /dev/null +++ b/.windsurf/rules/performance.md @@ -0,0 +1,98 @@ +# Performance Rules + +## Frontend Performance + +### Component Optimization +- Use React.memo for expensive components +- Implement useMemo for heavy calculations +- Avoid unnecessary re-renders +- Use useCallback for event handlers passed to child components +- Optimize state updates with batch processing + +### Bundle Size +- Implement code splitting +- Lazy load components when appropriate +- Set up proper tree shaking +- Minimize third-party dependencies +- Analyze bundle size regularly + +### Rendering Performance +- Keep render functions pure and efficient +- Avoid inline functions and object literals in JSX +- Use virtualization for long lists +- Optimize component hierarchies +- Minimize DOM mutations + +## API Performance + +### Request Optimization +- Batch API calls when possible +- Implement data pagination +- Use GraphQL for complex data requirements +- Optimize payload size +- Cache responses appropriately + +### Lightning Network Integration +- Implement proper caching for wallet balances +- Optimize transaction validation +- Use efficient lightning node configurations +- Batch transaction processing where possible + +## Caching Strategies + +### Client-Side Caching +- Use React Query for data fetching and caching +- Implement local storage for user preferences +- Set up proper cache invalidation +- Use memory caching for frequently accessed data + +### Server-Side Caching +- Cache API responses +- Implement Redis for shared caching +- Set up proper TTL for cached items +- Cache external API responses (LNbits, etc.) + +## Network Optimization + +### Asset Delivery +- Use CDN for static assets +- Implement proper compression +- Set up HTTP/2 or HTTP/3 +- Optimize asset size +- Use browser caching + +### API Communication +- Minimize payload size +- Use compression for API responses +- Implement connection pooling +- Optimize request/response cycles + +## Performance Monitoring + +### Metrics Collection +- Track core web vitals +- Monitor API response times +- Track component render times +- Set up real user monitoring +- Implement synthetic monitoring + +### Performance Budgets +- Set maximum bundle size +- Define target load times +- Establish memory usage limits +- Monitor time to interactive +- Track first contentful paint + +## Performance Testing + +### Load Testing +- Test application under expected load +- Identify performance bottlenecks +- Establish baseline performance metrics +- Test scaling capabilities + +### Optimization Process +- Regular performance audits +- Implement performance regression testing +- Document optimization strategies +- Prioritize high-impact optimizations diff --git a/.windsurf/rules/security.md b/.windsurf/rules/security.md new file mode 100644 index 000000000..f66c14b6c --- /dev/null +++ b/.windsurf/rules/security.md @@ -0,0 +1,90 @@ +# Security Rules + +## Authentication & Authorization + +### SSO Authentication +- Use Microsoft Teams SSO for user authentication +- Implement proper token validation +- Set appropriate token expiration times +- Store authentication tokens securely +- Never expose tokens in client-side code + +### Authorization +- Implement role-based access control +- Verify user permissions for each protected action +- Apply principle of least privilege +- Document access control policies + +## Bitcoin/Lightning Network Security + +### Wallet Management +- Secure storage of wallet credentials +- Use environment variables for sensitive data +- Implement transaction limits +- Apply proper validation for all payment operations +- Keep Lightning Node software updated + +### LNbits Integration +- Use API keys with minimal required permissions +- Rotate API keys regularly +- Validate all inputs from LNbits +- Implement proper error handling for API failures +- Log all transactions for audit purposes + +## Data Protection + +### User Data +- Encrypt sensitive user data at rest +- Use HTTPS for all communications +- Implement proper data retention policies +- Apply data minimization principles +- Obtain consent for data collection + +### Transaction Data +- Encrypt all transaction records +- Implement access controls for transaction history +- Audit trail for all zap transactions +- Secure backup of transaction data + +## Vulnerability Management + +### Code Security +- Perform security code reviews +- Use static analysis tools +- Avoid hardcoded secrets +- Update dependencies regularly +- Follow OWASP security guidelines + +### Dependency Management +- Regular security audits of dependencies +- Use dependency scanning tools +- Define a process for dependency updates +- Document known vulnerabilities and mitigations + +## API Security + +### Input Validation +- Validate all user inputs +- Implement proper error handling +- Rate limit API endpoints +- Prevent common attacks (XSS, CSRF, injection) + +### Secure API Design +- Use API tokens for authentication +- Implement proper CORS policies +- Log all API access +- Document API security requirements + +## Incident Response + +### Monitoring +- Log security events +- Implement alerting for suspicious activities +- Regular security reviews +- Document security incident response procedures + +### Response Plan +- Define roles and responsibilities +- Document containment procedures +- Establish communication protocols +- Implement recovery procedures diff --git a/.windsurf/rules/testing.md b/.windsurf/rules/testing.md new file mode 100644 index 000000000..14cf0f3f8 --- /dev/null +++ b/.windsurf/rules/testing.md @@ -0,0 +1,74 @@ +# Testing Rules + +## Test Coverage +- Minimum 80% test coverage +- 100% coverage for critical paths +- Test all error cases +- Test all user flows + +## Test Types +- Unit tests for components +- Integration tests for API calls +- E2E tests for user flows +- Performance tests for critical paths + +## Test Structure +- One test file per component +- Group related tests +- Clear test descriptions +- Isolated test environments + +### Unit Tests +- Test component props +- Test state changes +- Test event handlers +- Test rendering + +### Integration Tests +- Test API endpoints +- Test data flow +- Test error handling +- Test authentication + +### E2E Tests +- Test complete flows +- Test user interactions +- Test error states +- Test edge cases + +## Automated UI Testing +- Use Playwright for all UI automation tests +- Create test scripts for critical user journeys +- Test across multiple browsers (Chrome, Firefox, Edge) +- Implement visual regression testing +- Record videos of failed tests +- Use Page Object Model pattern +- Implement CI/CD pipeline integration +- Run tests in both headless and headed modes +- Create reusable test fixtures +- Implement retry logic for flaky tests + +## Best Practices +- Write tests before code +- Keep tests independent +- Mock external dependencies +- Use proper test data +- Clean up after tests + +## Performance Testing +- Test response times +- Test memory usage +- Test under load +- Test error recovery + +## Security Testing +- Test authentication +- Test authorization +- Test data validation +- Test error handling + +## Documentation +- Document test setup +- Document test data +- Document test assumptions +- Document test limitations diff --git a/docs/requirements.yaml b/docs/requirements.yaml new file mode 100644 index 000000000..733e00433 --- /dev/null +++ b/docs/requirements.yaml @@ -0,0 +1,315 @@ +# Zapp.ie (Copilot MVP) Requirements + +- project: "Zapp.ie (Copilot MVP)" + description: "A team engagement and recognition platform using micro-Bitcoin rewards through the Bitcoin Lightning Network" + features: + - name: "Total Zaps Sent Component" + id: total-zaps + description: "Component displaying total zaps sent statistics" + deliverables: + - "React component implementation" + - "Filter functionality (7-days, 30-days, 60-days)" + - "Satoshis (Sats) calculations" + user_stories: + - "As a Stakeholder, I would like Total Zaps Sent Component to be reviewed" + - "As a User, I would like to see filter the zaps sent by 7-days, 30-days or 60-days" + - "As a Teammate, I want to see the Total Zaps sent" + scenarios: + - name: "Display Total Zaps" + given: "User is on Feed page" + when: "Total zaps sent component loads" + then: + - "Total number of zaps is displayed in Sats" + - "Value is accurate and up-to-date" + + - name: "Display Average per User" + given: "User is on Feed page" + when: "Component loads" + then: + - "Average per user value is calculated" + - "Value is displayed in Sats" + - "Value represents total zaps divided by total users" + + - name: "Display Average per Day" + given: "User is on Feed page" + when: "Component loads" + then: + - "Average per day value is calculated" + - "Value is displayed in Sats" + - "Value represents total zaps divided by days since first zap" + + - name: "Display Biggest Zap" + given: "User is on Feed page" + when: "Component loads" + then: + - "Biggest zap value is displayed in Sats" + - "Value represents highest single zap transaction" + + - name: "Display Zaps from Copilots" + given: "User is on Feed page" + when: "Component loads" + then: + - "Total Sats sent by copilots is calculated" + - "Value is displayed in Sats" + + - name: "Display Zaps to Copilots" + given: "User is on Feed page" + when: "Component loads" + then: + - "Total Sats received by copilots is calculated" + - "Value is displayed in Sats" + + - name: "Leaderboard Component" + id: leaderboard + description: "Component showing zap rankings among teammates" + deliverables: + - "React leaderboard component" + - "Time period filtering (7 days, 30 days, 90 days)" + - "User ranking calculations" + user_stories: + - "As a Stakeholder, I would like Leaderboard component to be reviewed" + - "As a Teammate, I want to see a leaderboard of Zaps" + - "As a Teammate, I would like to filter by 7 days, 30 days and 90 days" + scenarios: + - name: "Display Leaderboard" + given: "User accesses leaderboard" + when: "Component loads" + then: + - "List of users is displayed with their zap counts" + - "Users are ranked by zap count" + - "Time period filter is available" + + - name: "React App - SSO Authentication" + id: sso-auth + description: "Single Sign-On authentication system" + deliverables: + - "Authentication integration" + - "Login page" + - "Error handling" + user_stories: + - "As a Stakeholder, I would like SSO Authentication to be reviewed" + - "As a Teammate, I want to log in using a SSO authentication process" + scenarios: + - name: "Login Page Display" + given: "User navigates to login page" + when: "Page loads" + then: + - "Login prompt is displayed" + - "Login button is visible" + + - name: "Login Form Display" + when: "User clicks login button" + then: + - "Redirected to authentication page" + - "Login form with email and password fields is displayed" + - "Cancel and Login buttons are present" + - "Forgot password link is available" + + - name: "Failed Login" + given: "User attempts login with invalid credentials" + when: "Authentication fails" + then: + - "Error message is displayed" + - "Message reads 'Invalid credentials, please try again.'" + + - name: "React App - Rewards Carousel Component" + id: rewards-carousel + description: "Component displaying available rewards for redemption" + deliverables: + - "Rewards carousel implementation" + - "Reward redemption functionality" + - "Product details integration" + user_stories: + - "As a Stakeholder, I would like Rewards carousel component to be reviewed" + - "As a Teammate, I want to see the available rewards" + - "As a user, I want to be able to purchase a reward" + - "As a Teammate, I would like to redeem the reward" + - "As a user, I want to see the available rewards" + scenarios: + - name: "View Rewards" + given: "User is on rewards screen" + when: "Page loads" + then: + - "List of rewards is displayed" + - "Each reward shows product details" + - "Redeem button is available" + + - name: "Redeem Reward" + given: "User has sufficient Sats" + when: "User clicks Buy button" + then: + - "QR code confirmation dialog is displayed" + - "Sats are deducted from user's account" + - "Confirmation of successful redemption" + - "Reward marked as redeemed" + + - name: "React App - Allowance Component" + id: allowance + description: "Component managing user's zap sending allowance" + deliverables: + - "Allowance balance display" + - "Send/Receive functionality" + - "Weekly allowance tracking" + user_stories: + - "As a Stakeholder, I would like Allowance component to be reviewed" + - "As a user, I would like to be able to see my allowance remaining" + - "As a Teammate, I want to see how many Zaps I have available to give to peers, so that I can plan my allocations" + scenarios: + - name: "Display Allowance Balance" + given: "User views Allowance component" + when: "Component loads" + then: + - "Total Sats available is displayed" + - "Amount is formatted with commas" + + - name: "Display Weekly Allowance" + given: "User views Allowance component" + when: "Component loads" + then: + - "Remaining weekly allowance is displayed" + - "Sent this week amount is displayed" + - "Both values are formatted clearly" + + - name: "Receive Functionality" + given: "User clicks Receive button" + when: "Modal appears" + then: + - "Wallet address/QR code generation" + - "Address/QR code is functional" + + - name: "Send Functionality" + given: "User clicks Send button" + when: "Modal appears" + then: + - "Recipient information input" + - "Transaction details input" + - "Send up to remaining weekly balance" + + - name: "React App - Wallet - Transaction History" + id: transaction-history + description: "Component displaying user's transaction history" + deliverables: + - "Transaction history component" + - "Tab-based filtering (All, Sent, Received)" + - "Transaction details display" + user_stories: + - "As a Stakeholder, I would like Wallet - Transaction History to be reviewed" + - "As a Teammate, I would like to have transaction history" + scenarios: + - name: "Display All Transactions" + given: "User is logged in" + when: "User views All tab" + then: + - "All sent and received transactions are displayed" + + - name: "Display Sent Transactions" + given: "User is logged in" + when: "User views Sent tab" + then: + - "All sent transactions are displayed" + - "Recipient name, amount in Sats, USD value, and reason are shown" + + - name: "Display Received Transactions" + given: "User is logged in" + when: "User views Received tab" + then: + - "All received transactions are displayed" + - "Sender name, amount in Sats, USD value, and reason are shown" + + - name: "React App - Wallet - Send & Receive Payment" + id: payment + description: "Component handling zap sending and receiving" + deliverables: + - "Send payment functionality" + - "Receive payment functionality" + - "QR code scanning" + user_stories: + - "As a Stakeholder, I would like Wallet - Send & Receive Payment to be reviewed" + - "As a Teammate, I want to see the amount of Sats in the currency" + - "As a user, I would like to be able to create an invoice (to receive a payment)" + - "As a Teammate, I would like to be able to send and receive payment" + scenarios: + - name: "Receive Zaps" + given: "User clicks Receive Zaps button" + when: "Receive popup displays" + then: + - "Amount specification form is shown" + - "Pre-set amount buttons available" + - "QR code generation for invoice" + + - name: "Send Zaps" + given: "User clicks Send button" + when: "Send popup displays" + then: + - "Amount specification form is shown" + - "Invoice pasting field available" + - "Anonymous sending option" + + - name: "QR Code Scanning" + given: "User is on send zaps popup" + when: "User clicks Scan QR code" + then: + - "QR code scanning functionality" + - "Device camera access" + + - name: "Bot - Zap Received Notification" + id: zap-notification + description: "Bot notification system for zap receipts" + deliverables: + - "Notification bot implementation" + - "Zap receipt alerts" + - "User recognition system" + user_stories: + - "As a Stakeholder, I would like Notification - Zap received to be reviewed" + - "As a Teammate, I want to be notified when I receive Zaps from peers, so that I'm aware of the recognition I've received and feel motivated to continue participating" + - "As a user, I want to allocate Zaps to my peers for their contributions, so that I can appreciate and reward their efforts" + scenarios: + - name: "Notify Zap Receipt" + given: "User receives zap" + when: "Zap is received" + then: + - "Notification is sent" + - "User is informed of zap receipt" + - "User is motivated to continue participation" + - "Peer recognition is visible" + + - name: "LNBits Allowance Extension" + id: lnbits-allowance + description: "LNBits marketplace extension for allowance management" + deliverables: + - "Marketplace extension" + - "Schedule viewing" + - "Schedule updating" + user_stories: + - "As an Administrator, I would like this extension available in the marketplace" + - "As a Stakeholder, I would like Allowance schedule to be reviewed" + scenarios: + - name: "Marketplace Availability" + given: "User accesses LNBits marketplace" + when: "Allowance extension is published" + then: + - "Extension is visible" + - "Extension is available for installation" + + - name: "Schedule Management" + given: "User installs extension" + when: "Schedule is modified" + then: + - "Changes are saved" + - "Information is updated" + + - name: "React App - User List Component" + id: user-list + description: "Component displaying all system users" + deliverables: + - "User list component" + - "User information display" + user_stories: + - "As a Stakeholder, I want a list of all users" + scenarios: + - name: "Display User List" + given: "User accesses component" + when: "Component loads" + then: + - "List of all users is displayed" + - "User information is visible"