---
description: when you need to understand the system architecture or make changes that impact the system architecture
alwaysApply: false
---
# TimeSafari Cross-Platform Architecture Guide

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Architecture guidelines

## 1. Platform Support Matrix

| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) |
|---------|-----------|--------------------|-------------------|
| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented |
| Deep Linking | URL Parameters | App URL Open Events | Not Implemented |
| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs |
| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented |
| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks |

## 2. Project Structure

### Core Directories

```
src/
├── components/     # Vue components
├── services/       # Platform services and business logic
├── views/          # Page components
├── router/         # Vue router configuration
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
├── lib/            # Core libraries
├── platforms/      # Platform-specific implementations
├── electron/       # Electron-specific code
├── constants/      # Application constants
├── db/             # Database related code
├── interfaces/     # TypeScript interfaces
└── assets/         # Static assets
```

### Entry Points

- `main.ts` → Base entry
- `main.common.ts` → Shared init
- `main.capacitor.ts` → Mobile entry
- `main.electron.ts` → Electron entry
- `main.web.ts` → Web entry

## 3. Service Architecture

### Service Organization

```tree
services/
├── QRScanner/           
│   ├── WebInlineQRScanner.ts
│   └── interfaces.ts
├── platforms/          
│   ├── WebPlatformService.ts
│   ├── CapacitorPlatformService.ts
│   └── ElectronPlatformService.ts
└── factory/           
    └── PlatformServiceFactory.ts
```

### Factory Pattern

Use a **singleton factory** to select platform services via
`process.env.VITE_PLATFORM`.

## 4. Feature Guidelines

### QR Code Scanning

- Define `QRScannerService` interface.
- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor,
  etc).
- Provide `addListener` and `onStream` hooks for composability.

### Deep Linking

- URL format: `timesafari://<route>[/<param>][?query=value]`
- Web: `router.beforeEach` → parse query
- Capacitor: `App.addListener("appUrlOpen", …)`

## 5. Build Process

- `vite.config.common.mts` → shared config
- Platform configs: `vite.config.web.mts`, `.capacitor.mts`,
  `.electron.mts`
- Use `process.env.VITE_PLATFORM` for conditional loading.

```bash
npm run build:web
npm run build:capacitor
npm run build:electron
```

## 6. Testing Strategy

- **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.

## 7. 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`).

## 8. 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).

## 9. Dependency Management

- Key deps: `@capacitor/core`, `electron`, `vue`.
- Use conditional `import()` for platform-specific libs.

## 10. Security Considerations

- **Permissions**: Always check + request gracefully.
- **Storage**: Secure storage for sensitive data; encrypt when possible.
- **Audits**: Schedule quarterly security reviews.

## 11. 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.

## 12. 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.

## 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?

---

**Status**: Active architecture guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: Vue 3, Capacitor, Electron, Vite
**Stakeholders**: Development team, Architecture team

- [ ] 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?  
# TimeSafari Cross-Platform Architecture Guide

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Architecture guidelines

## 1. Platform Support Matrix

| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) |
|---------|-----------|--------------------|-------------------|
| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented |
| Deep Linking | URL Parameters | App URL Open Events | Not Implemented |
| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs |
| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented |
| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks |

## 2. Project Structure

### Core Directories

```
src/
├── components/     # Vue components
├── services/       # Platform services and business logic
├── views/          # Page components
├── router/         # Vue router configuration
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
├── lib/            # Core libraries
├── platforms/      # Platform-specific implementations
├── electron/       # Electron-specific code
├── constants/      # Application constants
├── db/             # Database related code
├── interfaces/     # TypeScript interfaces
└── assets/         # Static assets
```

### Entry Points

- `main.ts` → Base entry
- `main.common.ts` → Shared init
- `main.capacitor.ts` → Mobile entry
- `main.electron.ts` → Electron entry
- `main.web.ts` → Web entry

## 3. Service Architecture

### Service Organization

```tree
services/
├── QRScanner/           
│   ├── WebInlineQRScanner.ts
│   └── interfaces.ts
├── platforms/          
│   ├── WebPlatformService.ts
│   ├── CapacitorPlatformService.ts
│   └── ElectronPlatformService.ts
└── factory/           
    └── PlatformServiceFactory.ts
```

### Factory Pattern

Use a **singleton factory** to select platform services via
`process.env.VITE_PLATFORM`.

## 4. Feature Guidelines

### QR Code Scanning

- Define `QRScannerService` interface.
- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor,
  etc).
- Provide `addListener` and `onStream` hooks for composability.

### Deep Linking

- URL format: `timesafari://<route>[/<param>][?query=value]`
- Web: `router.beforeEach` → parse query
- Capacitor: `App.addListener("appUrlOpen", …)`

## 5. Build Process

- `vite.config.common.mts` → shared config
- Platform configs: `vite.config.web.mts`, `.capacitor.mts`,
  `.electron.mts`
- Use `process.env.VITE_PLATFORM` for conditional loading.

```bash
npm run build:web
npm run build:capacitor
npm run build:electron
```

## 6. Testing Strategy

- **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.

## 7. 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`).

## 8. 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).

## 9. Dependency Management

- Key deps: `@capacitor/core`, `electron`, `vue`.
- Use conditional `import()` for platform-specific libs.

## 10. Security Considerations

- **Permissions**: Always check + request gracefully.
- **Storage**: Secure storage for sensitive data; encrypt when possible.
- **Audits**: Schedule quarterly security reviews.

## 11. 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.

## 12. 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.

## 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?

---

**Status**: Active architecture guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: Vue 3, Capacitor, Electron, Vite
**Stakeholders**: Development team, Architecture team

- [ ] 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?  
