# 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