Merge branch 'master' into android-safe-area-insets
This commit is contained in:
Jose Olarte III
@@ -1,7 +1,3 @@
|
||||
---
|
||||
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
|
||||
@@ -12,17 +8,20 @@ alwaysApply: false
|
||||
|
||||
| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) |
|
||||
|---------|-----------|--------------------|-------------------|
|
||||
| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented |
|
||||
| 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 |
|
||||
| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env
|
||||
checks |
|
||||
|
||||
## 2. Project Structure
|
||||
|
||||
### Core Directories
|
||||
|
||||
```
|
||||
|
||||
src/
|
||||
├── components/ # Vue components
|
||||
├── services/ # Platform services and business logic
|
||||
@@ -37,14 +36,19 @@ src/
|
||||
├── 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
|
||||
@@ -52,16 +56,18 @@ src/
|
||||
### Service Organization
|
||||
|
||||
```tree
|
||||
|
||||
services/
|
||||
├── QRScanner/
|
||||
├── QRScanner/
|
||||
│ ├── WebInlineQRScanner.ts
|
||||
│ └── interfaces.ts
|
||||
├── platforms/
|
||||
├── platforms/
|
||||
│ ├── WebPlatformService.ts
|
||||
│ ├── CapacitorPlatformService.ts
|
||||
│ └── ElectronPlatformService.ts
|
||||
└── factory/
|
||||
└── factory/
|
||||
└── PlatformServiceFactory.ts
|
||||
|
||||
```
|
||||
|
||||
### Factory Pattern
|
||||
@@ -74,279 +80,114 @@ Use a **singleton factory** to select platform services via
|
||||
### 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:
|
||||
- **Unit Tests**: Jest for business logic and utilities
|
||||
|
||||
```ts
|
||||
test.skip(!process.env.MOBILE_TEST, "Mobile-only test");
|
||||
```
|
||||
- **E2E Tests**: Playwright for critical user journeys
|
||||
|
||||
> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15
|
||||
> min) with QA to align on coverage and flaky test risks.
|
||||
- **Platform Tests**: Test platform-specific implementations
|
||||
|
||||
## 7. Error Handling
|
||||
- **Integration Tests**: Test service interactions
|
||||
|
||||
- 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`).
|
||||
## 7. Key Principles
|
||||
|
||||
## 8. Best Practices
|
||||
### Platform Independence
|
||||
|
||||
- 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).
|
||||
- **Abstract platform differences** behind interfaces
|
||||
|
||||
## 9. Dependency Management
|
||||
- **Use factory pattern** for service selection
|
||||
|
||||
- Key deps: `@capacitor/core`, `electron`, `vue`.
|
||||
- Use conditional `import()` for platform-specific libs.
|
||||
- **Maintain consistent APIs** across platforms
|
||||
|
||||
## 10. Security Considerations
|
||||
- **Graceful degradation** when features unavailable
|
||||
|
||||
- **Permissions**: Always check + request gracefully.
|
||||
- **Storage**: Secure storage for sensitive data; encrypt when possible.
|
||||
- **Audits**: Schedule quarterly security reviews.
|
||||
### Code Organization
|
||||
|
||||
## 11. ADR Process
|
||||
- **Single responsibility** for each service
|
||||
|
||||
- All major architecture choices → log in `doc/adr/`.
|
||||
- Use ADR template with Context, Decision, Consequences, Status.
|
||||
- Link related ADRs in PR descriptions.
|
||||
- **Interface segregation** for platform services
|
||||
|
||||
> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min
|
||||
> design sync for discussion, not just async review.
|
||||
- **Dependency injection** via mixins
|
||||
|
||||
## 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?
|
||||
- **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**: High
|
||||
**Priority**: Critical
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: Vue 3, Capacitor, Electron, Vite
|
||||
**Dependencies**: timesafari.mdc
|
||||
**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?
|
||||
|
||||
---
|
||||
## Model Implementation Checklist
|
||||
|
||||
**Status**: Active architecture guidelines
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: Vue 3, Capacitor, Electron, Vite
|
||||
**Stakeholders**: Development team, Architecture team
|
||||
### Before Architectural Decisions
|
||||
|
||||
- [ ] 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?
|
||||
- [ ] **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
|
||||
|
||||
246
.cursor/rules/app/architectural_examples.mdc
Normal file
246
.cursor/rules/app/architectural_examples.mdc
Normal file
@@ -0,0 +1,246 @@
|
||||
# Time Safari Architecture — Examples and Testing
|
||||
|
||||
> **Agent role**: Reference this file for architectural examples and
|
||||
testing patterns when working with TimeSafari architecture.
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### Global Error Handler
|
||||
|
||||
```typescript
|
||||
|
||||
// main.ts
|
||||
app.config.errorHandler = (err, instance, info) => {
|
||||
const componentName = instance?.$options?.name || 'Unknown';
|
||||
logger.error(`[${componentName}] Vue error`, err, info);
|
||||
};
|
||||
|
||||
window.addEventListener('unhandledrejection', (event) => {
|
||||
logger.error('[Global] Unhandled promise rejection', event.reason);
|
||||
});
|
||||
|
||||
```
|
||||
|
||||
### Platform-Specific Error Wrapping
|
||||
|
||||
```typescript
|
||||
|
||||
// services/platforms/CapacitorPlatformService.ts
|
||||
export class CapacitorPlatformService {
|
||||
async getFileContents(path: string): Promise<string> {
|
||||
try {
|
||||
const result = await Filesystem.readFile({
|
||||
path: path,
|
||||
encoding: 'utf8'
|
||||
});
|
||||
return result.data;
|
||||
} catch (error) {
|
||||
logger.error('[Capacitor API Error] Failed to read file', error, path);
|
||||
throw new Error(`Failed to read file: ${path}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
### Platform-Specific Test Skipping
|
||||
|
||||
```typescript
|
||||
|
||||
// tests/QRScanner.test.ts
|
||||
describe('QRScanner Service', () => {
|
||||
test('should start scanning on web', async () => {
|
||||
test.skip(process.env.VITE_PLATFORM !== 'web', 'Web-only test');
|
||||
|
||||
const scanner = new WebInlineQRScanner();
|
||||
await scanner.startScanning();
|
||||
// Assert scanning started
|
||||
});
|
||||
|
||||
test('should start scanning on mobile', async () => {
|
||||
test.skip(process.env.VITE_PLATFORM !== 'capacitor', 'Mobile-only test');
|
||||
|
||||
const scanner = new CapacitorQRScanner();
|
||||
await scanner.startScanning();
|
||||
// Assert scanning started
|
||||
});
|
||||
});
|
||||
|
||||
```
|
||||
|
||||
### Mock Service Testing
|
||||
|
||||
```typescript
|
||||
|
||||
// tests/mocks/QRScannerMock.ts
|
||||
export class QRScannerMock implements QRScannerService {
|
||||
private isScanning = false;
|
||||
private listeners: Map<string, Function[]> = new Map();
|
||||
|
||||
async startScanning(): Promise<void> {
|
||||
this.isScanning = true;
|
||||
this.emit('scanningStarted');
|
||||
}
|
||||
|
||||
async stopScanning(): Promise<void> {
|
||||
this.isScanning = false;
|
||||
this.emit('scanningStopped');
|
||||
}
|
||||
|
||||
addListener(event: string, callback: Function): void {
|
||||
if (!this.listeners.has(event)) {
|
||||
this.listeners.set(event, []);
|
||||
}
|
||||
this.listeners.get(event)!.push(callback);
|
||||
}
|
||||
|
||||
removeListener(event: string, callback: Function): void {
|
||||
const callbacks = this.listeners.get(event);
|
||||
if (callbacks) {
|
||||
const index = callbacks.indexOf(callback);
|
||||
if (index > -1) {
|
||||
callbacks.splice(index, 1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private emit(event: string, ...args: any[]): void {
|
||||
const callbacks = this.listeners.get(event);
|
||||
if (callbacks) {
|
||||
callbacks.forEach(callback => callback(...args));
|
||||
}
|
||||
}
|
||||
|
||||
getScanningState(): boolean {
|
||||
return this.isScanning;
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Service Composition
|
||||
|
||||
```typescript
|
||||
|
||||
// services/QRScannerService.ts
|
||||
export class QRScannerService {
|
||||
constructor(
|
||||
private platformService: PlatformService,
|
||||
private notificationService: NotificationService
|
||||
) {}
|
||||
|
||||
async startScanning(): Promise<void> {
|
||||
try {
|
||||
await this.platformService.startCamera();
|
||||
this.notificationService.show('Camera started');
|
||||
} catch (error) {
|
||||
this.notificationService.showError('Failed to start camera');
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Component Integration
|
||||
|
||||
```typescript
|
||||
|
||||
// components/QRScannerDialog.vue
|
||||
export default class QRScannerDialog extends Vue {
|
||||
@Inject() private qrScannerService!: QRScannerService;
|
||||
|
||||
async mounted() {
|
||||
try {
|
||||
await this.qrScannerService.startScanning();
|
||||
} catch (error) {
|
||||
this.$notify.error('Failed to start scanner');
|
||||
}
|
||||
}
|
||||
|
||||
beforeDestroy() {
|
||||
this.qrScannerService.stopScanning();
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Service Design
|
||||
|
||||
- Keep services focused and single-purpose
|
||||
|
||||
- Use dependency injection for service composition
|
||||
|
||||
- Implement proper error handling and logging
|
||||
|
||||
- Provide clear interfaces and contracts
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- Test platform-specific behavior separately
|
||||
|
||||
- Use mocks for external dependencies
|
||||
|
||||
- Test error conditions and edge cases
|
||||
|
||||
- Validate service contracts and interfaces
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Log errors with appropriate context
|
||||
|
||||
- Provide user-friendly error messages
|
||||
|
||||
- Implement graceful degradation
|
||||
|
||||
- Handle platform-specific error scenarios
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/app/architectural_decision_record.mdc` for
|
||||
|
||||
core architecture principles
|
||||
|
||||
- `.cursor/rules/app/architectural_implementation.mdc` for
|
||||
|
||||
implementation details
|
||||
|
||||
- `.cursor/rules/app/architectural_patterns.mdc` for core patterns
|
||||
|
||||
**Status**: Active examples and testing guide
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: architectural_patterns.mdc
|
||||
**Stakeholders**: Development team, Testing team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Architectural Examples
|
||||
|
||||
- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use
|
||||
case
|
||||
- [ ] **Service Design**: Plan service structure and dependencies
|
||||
- [ ] **Testing Strategy**: Plan testing approach for the example
|
||||
- [ ] **Error Handling**: Plan error handling and logging strategy
|
||||
|
||||
### During Architectural Examples
|
||||
|
||||
- [ ] **Service Implementation**: Implement focused, single-purpose services
|
||||
- [ ] **Dependency Injection**: Use proper dependency injection patterns
|
||||
- [ ] **Error Handling**: Implement proper error handling and logging
|
||||
- [ ] **Interface Design**: Provide clear interfaces and contracts
|
||||
|
||||
### After Architectural Examples
|
||||
|
||||
- [ ] **Testing Execution**: Test platform-specific behavior separately
|
||||
- [ ] **Service Validation**: Validate service contracts and interfaces
|
||||
- [ ] **Error Testing**: Test error conditions and edge cases
|
||||
- [ ] **Documentation**: Update architectural examples documentation
|
||||
139
.cursor/rules/app/architectural_implementation.mdc
Normal file
139
.cursor/rules/app/architectural_implementation.mdc
Normal file
@@ -0,0 +1,139 @@
|
||||
# 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
|
||||
214
.cursor/rules/app/architectural_patterns.mdc
Normal file
214
.cursor/rules/app/architectural_patterns.mdc
Normal file
@@ -0,0 +1,214 @@
|
||||
# Time Safari Architecture — Patterns and Examples
|
||||
|
||||
> **Agent role**: Reference this file for architectural patterns and
|
||||
> examples when working with TimeSafari architecture design.
|
||||
|
||||
## Architectural Patterns
|
||||
|
||||
### Factory Pattern Implementation
|
||||
|
||||
```typescript
|
||||
// PlatformServiceFactory.ts
|
||||
export class PlatformServiceFactory {
|
||||
private static instance: PlatformServiceFactory;
|
||||
|
||||
static getInstance(): PlatformServiceFactory {
|
||||
if (!PlatformServiceFactory.instance) {
|
||||
PlatformServiceFactory.instance = new PlatformServiceFactory();
|
||||
}
|
||||
return PlatformServiceFactory.instance;
|
||||
}
|
||||
|
||||
getQRScannerService(): QRScannerService {
|
||||
const platform = process.env.VITE_PLATFORM;
|
||||
|
||||
switch (platform) {
|
||||
case 'web':
|
||||
return new WebInlineQRScanner();
|
||||
case 'capacitor':
|
||||
return new CapacitorQRScanner();
|
||||
case 'electron':
|
||||
return new ElectronQRScanner();
|
||||
default:
|
||||
throw new Error(`Unsupported platform: ${platform}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Service Interface Definition
|
||||
|
||||
```typescript
|
||||
// interfaces/QRScannerService.ts
|
||||
export interface QRScannerService {
|
||||
startScanning(): Promise<void>;
|
||||
stopScanning(): Promise<void>;
|
||||
addListener(event: string, callback: Function): void;
|
||||
removeListener(event: string, callback: Function): void;
|
||||
}
|
||||
```
|
||||
|
||||
### Platform-Specific Implementation
|
||||
|
||||
```typescript
|
||||
// services/QRScanner/WebInlineQRScanner.ts
|
||||
export class WebInlineQRScanner implements QRScannerService {
|
||||
private listeners: Map<string, Function[]> = new Map();
|
||||
|
||||
async startScanning(): Promise<void> {
|
||||
// Web-specific implementation
|
||||
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
|
||||
// Process video stream for QR codes
|
||||
}
|
||||
|
||||
async stopScanning(): Promise<void> {
|
||||
// Stop video stream
|
||||
}
|
||||
|
||||
addListener(event: string, callback: Function): void {
|
||||
if (!this.listeners.has(event)) {
|
||||
this.listeners.set(event, []);
|
||||
}
|
||||
this.listeners.get(event)!.push(callback);
|
||||
}
|
||||
|
||||
removeListener(event: string, callback: Function): void {
|
||||
const callbacks = this.listeners.get(event);
|
||||
if (callbacks) {
|
||||
const index = callbacks.indexOf(callback);
|
||||
if (index > -1) {
|
||||
callbacks.splice(index, 1);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deep Linking Implementation
|
||||
|
||||
### URL Format
|
||||
|
||||
```
|
||||
timesafari://<route>[/<param>][?query=value]
|
||||
```
|
||||
|
||||
### Web Implementation
|
||||
|
||||
```typescript
|
||||
// router/index.ts
|
||||
router.beforeEach((to, from, next) => {
|
||||
// Parse deep link parameters
|
||||
if (to.query.deepLink) {
|
||||
const deepLink = to.query.deepLink as string;
|
||||
// Process deep link
|
||||
handleDeepLink(deepLink);
|
||||
}
|
||||
next();
|
||||
});
|
||||
|
||||
function handleDeepLink(deepLink: string) {
|
||||
// Parse and route deep link
|
||||
const url = new URL(deepLink);
|
||||
const route = url.pathname;
|
||||
const params = url.searchParams;
|
||||
|
||||
// Navigate to appropriate route
|
||||
router.push({ name: route, query: Object.fromEntries(params) });
|
||||
}
|
||||
```
|
||||
|
||||
### Capacitor Implementation
|
||||
|
||||
```typescript
|
||||
// main.capacitor.ts
|
||||
import { App } from '@capacitor/app';
|
||||
|
||||
App.addListener('appUrlOpen', (data) => {
|
||||
const url = data.url;
|
||||
// Parse deep link and navigate
|
||||
handleDeepLink(url);
|
||||
});
|
||||
```
|
||||
|
||||
## Platform Detection
|
||||
|
||||
### Feature Detection vs Platform Detection
|
||||
|
||||
```typescript
|
||||
// ✅ Good: Feature detection
|
||||
function hasCameraAccess(): boolean {
|
||||
return 'mediaDevices' in navigator &&
|
||||
'getUserMedia' in navigator.mediaDevices;
|
||||
}
|
||||
|
||||
// ❌ Bad: Platform detection
|
||||
function isWeb(): boolean {
|
||||
return process.env.VITE_PLATFORM === 'web';
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Imports
|
||||
|
||||
```typescript
|
||||
// services/platforms/index.ts
|
||||
export async function getPlatformService() {
|
||||
const platform = process.env.VITE_PLATFORM;
|
||||
|
||||
switch (platform) {
|
||||
case 'capacitor':
|
||||
const { CapacitorPlatformService } =
|
||||
await import('./CapacitorPlatformService');
|
||||
return new CapacitorPlatformService();
|
||||
case 'electron':
|
||||
const { ElectronPlatformService } =
|
||||
await import('./ElectronPlatformService');
|
||||
return new ElectronPlatformService();
|
||||
default:
|
||||
const { WebPlatformService } =
|
||||
await import('./WebPlatformService');
|
||||
return new WebPlatformService();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/app/architectural_decision_record.mdc` for core
|
||||
architecture principles
|
||||
- `.cursor/rules/app/architectural_implementation.mdc` for
|
||||
implementation details
|
||||
- `.cursor/rules/app/architectural_examples.mdc` for examples and
|
||||
testing patterns
|
||||
|
||||
**Status**: Active patterns and examples
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: architectural_decision_record.mdc,
|
||||
architectural_implementation.mdc
|
||||
**Stakeholders**: Development team, Architecture team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Architectural Patterns
|
||||
|
||||
- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use
|
||||
case
|
||||
- [ ] **Platform Analysis**: Identify platform-specific requirements
|
||||
- [ ] **Service Planning**: Plan service structure and dependencies
|
||||
- [ ] **Testing Strategy**: Plan testing approach for the pattern
|
||||
|
||||
### During Architectural Patterns
|
||||
|
||||
- [ ] **Pattern Implementation**: Implement chosen architectural pattern
|
||||
- [ ] **Platform Abstraction**: Use platform abstraction layers appropriately
|
||||
- [ ] **Service Composition**: Compose services using dependency injection
|
||||
- [ ] **Interface Design**: Provide clear interfaces and contracts
|
||||
|
||||
### After Architectural Patterns
|
||||
|
||||
- [ ] **Pattern Validation**: Verify pattern is implemented correctly
|
||||
- [ ] **Platform Testing**: Test across all target platforms
|
||||
- [ ] **Service Testing**: Test service composition and dependencies
|
||||
- [ ] **Documentation**: Update architectural patterns documentation
|
||||
@@ -1,3 +1,6 @@
|
||||
---
|
||||
alwaysApply: false
|
||||
---
|
||||
# Time Safari Context
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
@@ -15,10 +18,12 @@ that preserve privacy and data sovereignty.
|
||||
## Core Goals
|
||||
|
||||
1. **Connect**: Make it easy, rewarding, and non-threatening for people to
|
||||
|
||||
connect with others who have similar interests, and to initiate activities
|
||||
together.
|
||||
|
||||
2. **Reveal**: Widely advertise the great support and rewards that are being
|
||||
|
||||
given and accepted freely, especially non-monetary ones, showing the impact
|
||||
gifts make in people's lives.
|
||||
|
||||
@@ -27,29 +32,45 @@ that preserve privacy and data sovereignty.
|
||||
### Architecture
|
||||
|
||||
- **Privacy-preserving claims architecture** via endorser.ch
|
||||
|
||||
- **Decentralized Identifiers (DIDs)**: User identities based on
|
||||
|
||||
public/private key pairs stored on devices
|
||||
|
||||
- **Cryptographic Verification**: All claims and confirmations are
|
||||
|
||||
cryptographically signed
|
||||
|
||||
- **User-Controlled Visibility**: Users explicitly control who can see their
|
||||
|
||||
identifiers and data
|
||||
|
||||
- **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron)
|
||||
|
||||
### Current Database State
|
||||
|
||||
- **Database**: SQLite via Absurd SQL (browser) and native SQLite
|
||||
|
||||
(mobile/desktop)
|
||||
|
||||
- **Legacy Support**: IndexedDB (Dexie) for backward compatibility
|
||||
|
||||
- **Status**: Modern database architecture fully implemented
|
||||
|
||||
### Core Technologies
|
||||
|
||||
- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator
|
||||
|
||||
- **Styling**: TailwindCSS
|
||||
|
||||
- **Build**: Vite with platform-specific configs
|
||||
|
||||
- **Testing**: Playwright E2E, Jest unit tests
|
||||
|
||||
- **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy)
|
||||
|
||||
- **State**: Pinia stores
|
||||
|
||||
- **Platform Services**: Abstracted behind interfaces with factory pattern
|
||||
|
||||
## Development Principles
|
||||
@@ -57,22 +78,31 @@ that preserve privacy and data sovereignty.
|
||||
### Code Organization
|
||||
|
||||
- **Platform Services**: Abstract platform-specific code behind interfaces
|
||||
|
||||
- **Service Factory**: Use `PlatformServiceFactory` for platform selection
|
||||
|
||||
- **Type Safety**: Strict TypeScript, no `any` types, use type guards
|
||||
|
||||
- **Modern Architecture**: Use current platform service patterns
|
||||
|
||||
### Architecture Patterns
|
||||
|
||||
- **Dependency Injection**: Services injected via mixins and factory pattern
|
||||
|
||||
- **Interface Segregation**: Small, focused interfaces over large ones
|
||||
|
||||
- **Composition over Inheritance**: Prefer mixins and composition
|
||||
|
||||
- **Single Responsibility**: Each component/service has one clear purpose
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- **E2E**: Playwright for critical user journeys
|
||||
|
||||
- **Unit**: Jest with F.I.R.S.T. principles
|
||||
|
||||
- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI
|
||||
|
||||
- **Quality Assurance**: Comprehensive testing and validation
|
||||
|
||||
## Current Development Focus
|
||||
@@ -80,102 +110,64 @@ that preserve privacy and data sovereignty.
|
||||
### Active Development
|
||||
|
||||
- **Feature Development**: Build new functionality using modern platform
|
||||
|
||||
services
|
||||
|
||||
- **Performance Optimization**: Improve app performance and user experience
|
||||
|
||||
- **Platform Enhancement**: Leverage platform-specific capabilities
|
||||
|
||||
- **Code Quality**: Maintain high standards and best practices
|
||||
|
||||
### Development Metrics
|
||||
|
||||
- **Code Quality**: High standards maintained across all platforms
|
||||
|
||||
- **Performance**: Optimized for all target devices
|
||||
|
||||
- **Testing**: Comprehensive coverage maintained
|
||||
|
||||
- **User Experience**: Focus on intuitive, accessible interfaces
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
### Web (PWA)
|
||||
|
||||
- **QR Scanning**: WebInlineQRScanner
|
||||
- **Deep Linking**: URL parameters
|
||||
- **File System**: Limited browser APIs
|
||||
- **Build**: `npm run build:web` (development build)
|
||||
|
||||
### Mobile (Capacitor)
|
||||
|
||||
- **QR Scanning**: @capacitor-mlkit/barcode-scanning
|
||||
- **Deep Linking**: App URL open events
|
||||
- **File System**: Capacitor Filesystem
|
||||
- **Build**: `npm run build:capacitor`
|
||||
|
||||
### Desktop (Electron)
|
||||
|
||||
- **File System**: Node.js fs
|
||||
- **Build**: `npm run build:electron`
|
||||
- **Distribution**: AppImage, DEB, DMG packages
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# Web (development)
|
||||
npm run build:web
|
||||
|
||||
# Mobile
|
||||
npm run build:capacitor
|
||||
npm run build:native
|
||||
|
||||
# Desktop
|
||||
npm run build:electron
|
||||
npm run build:electron:appimage
|
||||
npm run build:electron:deb
|
||||
npm run build:electron:dmg
|
||||
```
|
||||
|
||||
### Testing Commands
|
||||
|
||||
```bash
|
||||
# Web E2E
|
||||
npm run test:web
|
||||
|
||||
# Mobile
|
||||
npm run test:mobile
|
||||
npm run test:android
|
||||
npm run test:ios
|
||||
|
||||
# Type checking
|
||||
npm run type-check
|
||||
npm run lint-fix
|
||||
```
|
||||
|
||||
## Key Constraints
|
||||
|
||||
1. **Privacy First**: User identifiers remain private except when explicitly
|
||||
shared
|
||||
2. **Platform Compatibility**: Features must work across all target platforms
|
||||
3. **Performance**: Must remain performant on older/simpler devices
|
||||
4. **Modern Architecture**: New features should use current platform services
|
||||
5. **Offline Capability**: Key functionality should work offline when feasible
|
||||
|
||||
## Use Cases to Support
|
||||
|
||||
1. **Community Building**: Tools for finding others with shared interests
|
||||
2. **Project Coordination**: Easy proposal and collaboration on projects
|
||||
3. **Reputation Building**: Showcasing contributions and reliability
|
||||
4. **Governance**: Facilitating decision-making and collective governance
|
||||
|
||||
## Resources
|
||||
|
||||
- **Testing**: `docs/migration-testing/`
|
||||
- **Architecture**: `docs/architecture-decisions.md`
|
||||
- **Build Context**: `docs/build-modernization-context.md`
|
||||
|
||||
---
|
||||
|
||||
## Status: Active application context
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details
|
||||
|
||||
- `.cursor/rules/app/timesafari_development.mdc` for
|
||||
|
||||
development workflow details
|
||||
|
||||
**Status**: Active application context
|
||||
**Priority**: Critical
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team, Product team
|
||||
|
||||
- **Priority**: Critical
|
||||
- **Estimated Effort**: Ongoing reference
|
||||
- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron
|
||||
|
||||
- **Stakeholders**: Development team, Product team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before TimeSafari Development
|
||||
|
||||
- [ ] **Application Context**: Understand TimeSafari's community-building purpose
|
||||
- [ ] **Platform Analysis**: Identify target platforms (web, mobile, desktop)
|
||||
- [ ] **Architecture Review**: Review current platform service patterns
|
||||
- [ ] **Testing Strategy**: Plan testing approach for all platforms
|
||||
|
||||
### During TimeSafari Development
|
||||
|
||||
- [ ] **Platform Services**: Use abstracted platform services via interfaces
|
||||
- [ ] **Type Safety**: Implement strict TypeScript with type guards
|
||||
- **Modern Architecture**: Follow current platform service patterns
|
||||
- [ ] **Performance Focus**: Ensure performance on all target devices
|
||||
|
||||
### After TimeSafari Development
|
||||
|
||||
- [ ] **Cross-Platform Testing**: Test functionality across all platforms
|
||||
- [ ] **Performance Validation**: Verify performance meets requirements
|
||||
- [ ] **Code Quality**: Ensure high standards maintained
|
||||
- [ ] **Documentation Update**: Update relevant documentation
|
||||
|
||||
174
.cursor/rules/app/timesafari_development.mdc
Normal file
174
.cursor/rules/app/timesafari_development.mdc
Normal file
@@ -0,0 +1,174 @@
|
||||
# Time Safari Development — Workflow and Processes
|
||||
|
||||
> **Agent role**: Reference this file for development workflow details when
|
||||
working with TimeSafari development processes.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
|
||||
# Web (development)
|
||||
|
||||
npm run build:web
|
||||
|
||||
# Mobile
|
||||
|
||||
npm run build:capacitor
|
||||
npm run build:native
|
||||
|
||||
# Desktop
|
||||
|
||||
npm run build:electron
|
||||
npm run build:electron:appimage
|
||||
npm run build:electron:deb
|
||||
npm run build:electron:dmg
|
||||
|
||||
```
|
||||
|
||||
### Testing Commands
|
||||
|
||||
```bash
|
||||
|
||||
# Web E2E
|
||||
|
||||
npm run test:web
|
||||
|
||||
# Mobile
|
||||
|
||||
npm run test:mobile
|
||||
npm run test:android
|
||||
npm run test:ios
|
||||
|
||||
# Type checking
|
||||
|
||||
npm run type-check
|
||||
npm run lint-fix
|
||||
|
||||
```
|
||||
|
||||
## Development Principles
|
||||
|
||||
### Code Organization
|
||||
|
||||
- **Platform Services**: Abstract platform-specific code behind interfaces
|
||||
|
||||
- **Service Factory**: Use `PlatformServiceFactory` for platform selection
|
||||
|
||||
- **Type Safety**: Strict TypeScript, no `any` types, use type guards
|
||||
|
||||
- **Modern Architecture**: Use current platform service patterns
|
||||
|
||||
### Architecture Patterns
|
||||
|
||||
- **Dependency Injection**: Services injected via mixins and factory pattern
|
||||
|
||||
- **Interface Segregation**: Small, focused interfaces over large ones
|
||||
|
||||
- **Composition over Inheritance**: Prefer mixins and composition
|
||||
|
||||
- **Single Responsibility**: Each component/service has one clear purpose
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- **E2E**: Playwright for critical user journeys
|
||||
|
||||
- **Unit**: Jest with F.I.R.S.T. principles
|
||||
|
||||
- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI
|
||||
|
||||
- **Quality Assurance**: Comprehensive testing and validation
|
||||
|
||||
## Current Development Focus
|
||||
|
||||
### Active Development
|
||||
|
||||
- **Feature Development**: Build new functionality using modern platform
|
||||
|
||||
services
|
||||
|
||||
- **Performance Optimization**: Improve app performance and user experience
|
||||
|
||||
- **Platform Enhancement**: Leverage platform-specific capabilities
|
||||
|
||||
- **Code Quality**: Maintain high standards and best practices
|
||||
|
||||
### Development Metrics
|
||||
|
||||
- **Code Quality**: High standards maintained across all platforms
|
||||
|
||||
- **Performance**: Optimized for all target devices
|
||||
|
||||
- **Testing**: Comprehensive coverage maintained
|
||||
|
||||
- **User Experience**: Focus on intuitive, accessible interfaces
|
||||
|
||||
## Development Environment
|
||||
|
||||
### Required Tools
|
||||
|
||||
- **Node.js**: LTS version with npm
|
||||
|
||||
- **Git**: Version control with proper branching strategy
|
||||
|
||||
- **IDE**: VS Code with recommended extensions
|
||||
|
||||
- **Platform Tools**: Android Studio, Xcode (for mobile development)
|
||||
|
||||
### Environment Setup
|
||||
|
||||
1. **Clone Repository**: `git clone <repository-url>`
|
||||
|
||||
2. **Install Dependencies**: `npm install`
|
||||
|
||||
3. **Environment Variables**: Copy `.env.example` to `.env.local`
|
||||
|
||||
4. **Platform Setup**: Follow platform-specific setup guides
|
||||
|
||||
### Quality Assurance
|
||||
|
||||
- **Linting**: ESLint with TypeScript rules
|
||||
|
||||
- **Formatting**: Prettier for consistent code style
|
||||
|
||||
- **Type Checking**: TypeScript strict mode enabled
|
||||
|
||||
- **Testing**: Comprehensive test coverage requirements
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/app/timesafari.mdc` for core application context
|
||||
|
||||
- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details
|
||||
|
||||
**Status**: Active development workflow
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: timesafari.mdc, timesafari_platforms.mdc
|
||||
**Stakeholders**: Development team, DevOps team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before TimeSafari Development
|
||||
|
||||
- [ ] **Environment Setup**: Verify development environment is ready
|
||||
- [ ] **Platform Tools**: Ensure platform-specific tools are available
|
||||
- [ ] **Dependencies**: Check all required dependencies are installed
|
||||
- [ ] **Environment Variables**: Configure local environment variables
|
||||
|
||||
### During TimeSafari Development
|
||||
|
||||
- [ ] **Platform Services**: Use modern platform service patterns
|
||||
- [ ] **Code Quality**: Follow ESLint and TypeScript strict rules
|
||||
- [ ] **Testing**: Implement comprehensive testing strategy
|
||||
- [ ] **Performance**: Optimize for all target platforms
|
||||
|
||||
### After TimeSafari Development
|
||||
|
||||
- [ ] **Quality Checks**: Run linting, formatting, and type checking
|
||||
- [ ] **Testing**: Execute comprehensive tests across platforms
|
||||
- [ ] **Performance Validation**: Verify performance meets requirements
|
||||
- [ ] **Documentation**: Update development documentation
|
||||
167
.cursor/rules/app/timesafari_platforms.mdc
Normal file
167
.cursor/rules/app/timesafari_platforms.mdc
Normal file
@@ -0,0 +1,167 @@
|
||||
# Time Safari Platforms — Platform-Specific Considerations
|
||||
|
||||
> **Agent role**: Reference this file for platform-specific details when working
|
||||
with TimeSafari development across different platforms.
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
### Web (PWA)
|
||||
|
||||
- **QR Scanning**: WebInlineQRScanner
|
||||
|
||||
- **Deep Linking**: URL parameters
|
||||
|
||||
- **File System**: Limited browser APIs
|
||||
|
||||
- **Build**: `npm run build:web` (development build)
|
||||
|
||||
### Mobile (Capacitor)
|
||||
|
||||
- **QR Scanning**: @capacitor-mlkit/barcode-scanning
|
||||
|
||||
- **Deep Linking**: App URL open events
|
||||
|
||||
- **File System**: Capacitor Filesystem
|
||||
|
||||
- **Build**: `npm run build:capacitor`
|
||||
|
||||
### Desktop (Electron)
|
||||
|
||||
- **File System**: Node.js fs
|
||||
|
||||
- **Build**: `npm run build:electron`
|
||||
|
||||
- **Distribution**: AppImage, DEB, DMG packages
|
||||
|
||||
## Platform Compatibility Requirements
|
||||
|
||||
### Cross-Platform Features
|
||||
|
||||
- **Core functionality** must work identically across all platforms
|
||||
|
||||
- **Platform-specific enhancements** should be additive, not required
|
||||
|
||||
- **Fallback behavior** must be graceful when platform features unavailable
|
||||
|
||||
### Platform-Specific Capabilities
|
||||
|
||||
- **Web**: Browser APIs, PWA features, responsive design
|
||||
|
||||
- **Mobile**: Native device features, offline capability, app store compliance
|
||||
|
||||
- **Desktop**: File system access, system integration, native performance
|
||||
|
||||
## Build and Distribution
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
|
||||
# Web (development)
|
||||
|
||||
npm run build:web
|
||||
|
||||
# Mobile
|
||||
|
||||
npm run build:capacitor
|
||||
npm run build:native
|
||||
|
||||
# Desktop
|
||||
|
||||
npm run build:electron
|
||||
npm run build:electron:appimage
|
||||
npm run build:electron:deb
|
||||
npm run build:electron:dmg
|
||||
|
||||
```
|
||||
|
||||
### Testing Commands
|
||||
|
||||
```bash
|
||||
|
||||
# Web E2E
|
||||
|
||||
npm run test:web
|
||||
|
||||
# Mobile
|
||||
|
||||
npm run test:mobile
|
||||
npm run test:android
|
||||
npm run test:ios
|
||||
|
||||
# Type checking
|
||||
|
||||
npm run type-check
|
||||
npm run lint-fix
|
||||
|
||||
```
|
||||
|
||||
## Key Constraints
|
||||
|
||||
1. **Privacy First**: User identifiers remain private except when explicitly
|
||||
|
||||
shared
|
||||
|
||||
2. **Platform Compatibility**: Features must work across all target platforms
|
||||
|
||||
3. **Performance**: Must remain performant on older/simpler devices
|
||||
|
||||
4. **Modern Architecture**: New features should use current platform services
|
||||
|
||||
5. **Offline Capability**: Key functionality should work offline when feasible
|
||||
|
||||
## Use Cases to Support
|
||||
|
||||
1. **Community Building**: Tools for finding others with shared interests
|
||||
|
||||
2. **Project Coordination**: Easy proposal and collaboration on projects
|
||||
|
||||
3. **Reputation Building**: Showcasing contributions and reliability
|
||||
|
||||
4. **Governance**: Facilitating decision-making and collective governance
|
||||
|
||||
## Resources
|
||||
|
||||
- **Testing**: `docs/migration-testing/`
|
||||
|
||||
- **Architecture**: `docs/architecture-decisions.md`
|
||||
|
||||
- **Build Context**: `docs/build-modernization-context.md`
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/app/timesafari.mdc` for core application context
|
||||
- `.cursor/rules/app/timesafari_development.mdc` for
|
||||
|
||||
development workflow details
|
||||
|
||||
**Status**: Active platform guidelines
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: timesafari.mdc
|
||||
**Stakeholders**: Development team, Platform teams
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Platform Development
|
||||
|
||||
- [ ] **Platform Analysis**: Identify all target platforms (web, mobile, desktop)
|
||||
- [ ] **Feature Requirements**: Understand feature requirements across platforms
|
||||
- [ ] **Platform Constraints**: Review platform-specific limitations and capabilities
|
||||
- [ ] **Testing Strategy**: Plan testing approach for all target platforms
|
||||
|
||||
### During Platform Development
|
||||
|
||||
- [ ] **Cross-Platform Implementation**: Implement features across all platforms
|
||||
- [ ] **Platform Services**: Use current platform services for new features
|
||||
- [ ] **Performance Optimization**: Ensure performance on older/simpler devices
|
||||
- [ ] **Offline Capability**: Implement offline functionality where feasible
|
||||
|
||||
### After Platform Development
|
||||
|
||||
- [ ] **Cross-Platform Testing**: Test functionality across all target platforms
|
||||
- [ ] **Performance Validation**: Verify performance meets requirements
|
||||
- [ ] **Documentation Update**: Update platform-specific documentation
|
||||
- [ ] **Team Communication**: Share platform implementation results with team
|
||||
Reference in New Issue
Block a user