forked from trent_larson/crowd-funder-for-time-pwa
refactor(cursor-rules): restructure rules architecture with meta-rule system
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
This commit is contained in:
139
.cursor/rules/app/architectural_implementation.mdc
Normal file
139
.cursor/rules/app/architectural_implementation.mdc
Normal file
@@ -0,0 +1,139 @@
|
||||
# Time Safari Architecture — Implementation Details
|
||||
|
||||
> **Agent role**: Reference this file for detailed implementation details when
|
||||
working with TimeSafari architecture implementation.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Global Vue error handler → logs with component name.
|
||||
|
||||
- Platform-specific wrappers log API errors with platform prefix
|
||||
|
||||
(`[Capacitor API Error]`, etc).
|
||||
|
||||
- Use structured logging (not `console.log`).
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Keep platform code **isolated** in `platforms/`.
|
||||
|
||||
- Always define a **shared interface** first.
|
||||
|
||||
- Use feature detection, not platform detection, when possible.
|
||||
|
||||
- Dependency injection for services → improves testability.
|
||||
|
||||
- Maintain **Competence Hooks** in PRs (2–3 prompts for dev
|
||||
|
||||
discussion).
|
||||
|
||||
## Dependency Management
|
||||
|
||||
- Key deps: `@capacitor/core`, `electron`, `vue`.
|
||||
|
||||
- Use conditional `import()` for platform-specific libs.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Permissions**: Always check + request gracefully.
|
||||
|
||||
- **Storage**: Secure storage for sensitive data; encrypt when possible.
|
||||
|
||||
- **Audits**: Schedule quarterly security reviews.
|
||||
|
||||
## ADR Process
|
||||
|
||||
- All major architecture choices → log in `doc/adr/`.
|
||||
|
||||
- Use ADR template with Context, Decision, Consequences, Status.
|
||||
|
||||
- Link related ADRs in PR descriptions.
|
||||
|
||||
> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min
|
||||
> design sync for discussion, not just async review.
|
||||
|
||||
## Collaboration Hooks
|
||||
|
||||
- **QR features**: Sync with Security before merging → permissions &
|
||||
|
||||
privacy.
|
||||
|
||||
- **New platform builds**: Demo in team meeting → confirm UX
|
||||
|
||||
differences.
|
||||
|
||||
- **Critical ADRs**: Present in guild or architecture review.
|
||||
|
||||
## Testing Implementation
|
||||
|
||||
- **Unit tests** for services.
|
||||
|
||||
- **Playwright** for Web + Capacitor:
|
||||
|
||||
- `playwright.config-local.ts` includes web + Pixel 5.
|
||||
|
||||
- **Electron tests**: add `spectron` or Playwright-Electron.
|
||||
|
||||
- Mark tests with platform tags:
|
||||
|
||||
```ts
|
||||
|
||||
test.skip(!process.env.MOBILE_TEST, "Mobile-only test");
|
||||
|
||||
```
|
||||
|
||||
> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15
|
||||
> min) with QA to align on coverage and flaky test risks.
|
||||
|
||||
## Self-Check
|
||||
|
||||
- [ ] Does this feature implement a shared interface?
|
||||
|
||||
- [ ] Are fallbacks + errors handled gracefully?
|
||||
|
||||
- [ ] Have relevant ADRs been updated/linked?
|
||||
|
||||
- [ ] Did I add competence hooks or prompts for the team?
|
||||
|
||||
- [ ] Was human interaction (sync/review/demo) scheduled?
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/app/architectural_decision_record.mdc` for
|
||||
|
||||
core architecture principles
|
||||
|
||||
- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and
|
||||
|
||||
examples
|
||||
|
||||
**Status**: Active implementation guidelines
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: architectural_decision_record.mdc
|
||||
**Stakeholders**: Development team, Architecture team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Architectural Implementation
|
||||
|
||||
- [ ] **Interface Review**: Verify feature implements shared interface
|
||||
- [ ] **ADR Review**: Check if ADR is required for major changes
|
||||
- [ ] **Security Assessment**: Assess security implications for QR features
|
||||
- [ ] **Platform Planning**: Plan platform-specific implementation details
|
||||
|
||||
### During Architectural Implementation
|
||||
|
||||
- [ ] **Interface Implementation**: Implement shared interfaces consistently
|
||||
- [ ] **Error Handling**: Implement graceful fallbacks and error handling
|
||||
- [ ] **Testing Strategy**: Plan unit tests for services and E2E tests
|
||||
- [ ] **Human Interaction**: Schedule syncs/reviews/demos as needed
|
||||
|
||||
### After Architectural Implementation
|
||||
|
||||
- [ ] **Interface Validation**: Verify shared interfaces are properly implemented
|
||||
- [ ] **Testing Execution**: Run unit tests and platform-specific tests
|
||||
- [ ] **ADR Updates**: Update relevant ADRs and link in PR descriptions
|
||||
- [ ] **Team Communication**: Share implementation results with team
|
||||
Reference in New Issue
Block a user