You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
139 lines
3.7 KiB
139 lines
3.7 KiB
# 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
|
|
|