# 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**: Jest for business logic and utilities

- **E2E Tests**: Playwright for critical user journeys

- **Platform Tests**: Test platform-specific implementations

- **Integration Tests**: Test service interactions

## 7. Key Principles

### Platform Independence

- **Abstract platform differences** behind interfaces

- **Use factory pattern** for service selection

- **Maintain consistent APIs** across platforms

- **Graceful degradation** when features unavailable

### Code Organization

- **Single responsibility** for each service

- **Interface segregation** for platform services

- **Dependency injection** via mixins

- **Composition over inheritance**

---

**See also**:

- `.cursor/rules/app/architectural_implementation.mdc` for

  detailed implementation details

- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and

  examples

**Status**: Active architecture guidelines
**Priority**: Critical
**Estimated Effort**: Ongoing reference
**Dependencies**: timesafari.mdc
**Stakeholders**: Development team, Architecture team

- [ ] Have relevant ADRs been updated/linked?

- [ ] Did I add competence hooks or prompts for the team?

- [ ] Was human interaction (sync/review/demo) scheduled?

## Model Implementation Checklist

### Before Architectural Decisions

- [ ] **Decision Context**: Understand the architectural challenge to be addressed
- [ ] **Stakeholder Identification**: Identify all decision makers and affected parties
- [ ] **Research**: Research alternatives and gather evidence
- [ ] **Impact Assessment**: Assess impact on existing architecture

### During Architectural Decisions

- [ ] **Context Documentation**: Document the context and forces at play
- [ ] **Decision Recording**: Record the decision and rationale clearly
- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences
- [ ] **Alternatives Documentation**: Document alternatives considered and why rejected

### After Architectural Decisions

- [ ] **ADR Creation**: Create or update Architectural Decision Record
- [ ] **Team Communication**: Communicate decision to all stakeholders
- [ ] **Implementation Planning**: Plan implementation of the architectural decision
- [ ] **Documentation Update**: Update relevant architectural documentation
