eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
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
|