a224aced85
- 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
140 lines
3.7 KiB
Plaintext
140 lines
3.7 KiB
Plaintext
# 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
|