Electron Code Review Mode Instructions

# Electron Code Review Mode Instructions

You're reviewing an Electron-based desktop app with:

- **Main Process**: Node.js (Electron Main)
- **Renderer Process**: Angular (Electron Renderer)
- **Integration**: Native integration layer (e.g., AppleScript, shell, or other tooling)

---

## Code Conventions

- Node.js: camelCase variables/functions, PascalCase classes
- Angular: PascalCase Components/Directives, camelCase methods/variables
- Avoid magic strings/numbers — use constants or env vars
- Strict async/await — avoid `.then()`, `.Result`, `.Wait()`, or callback mixing
- Manage nullable types explicitly

---

## Electron Main Process (Node.js)

### Architecture & Separation of Concerns

- Controller logic delegates to services — no business logic inside Electron IPC event listeners
- Use Dependency Injection (InversifyJS or similar)
- One clear entry point — index.ts or main.ts

### Async/Await & Error Handling

- No missing `await` on async calls
- No unhandled promise rejections — always `.catch()` or `try/catch`
- Wrap native calls (e.g., exiftool, AppleScript, shell commands) with robust error handling (timeout, invalid output, exit code checks)
- Use safe wrappers (child_process with `spawn` not `exec` for large data)

### Exception Handling

- Catch and log uncaught exceptions (`process.on('uncaughtException')`)
- Catch unhandled promise rejections (`process.on('unhandledRejection')`)
- Graceful process exit on fatal errors
- Prevent renderer-originated IPC from crashing main

### Security

- Enable context isolation
- Disable remote module
- Sanitize all IPC messages from renderer
- Never expose sensitive file system access to renderer
- Validate all file paths
- Avoid shell injection / unsafe AppleScript execution
- Harden access to system resources

### Memory & Resource Management

- Prevent memory leaks in long-running services
- Release resources after heavy operations (Streams, exiftool, child processes)
- Clean up temp files and folders
- Monitor memory usage (heap, native memory)
- Handle multiple windows safely (avoid window leaks)

### Performance

- Avoid synchronous file system access in main process (no `fs.readFileSync`)
- Avoid synchronous IPC (`ipcMain.handleSync`)
- Limit IPC call rate
- Debounce high-frequency renderer → main events
- Stream or batch large file operations

### Native Integration (Exiftool, AppleScript, Shell)

- Timeouts for exiftool / AppleScript commands
- Validate output from native tools
- Fallback/retry logic when possible
- Log slow commands with timing
- Avoid blocking main thread on native command execution

### Logging & Telemetry

- Centralized logging with levels (info, warn, error, fatal)
- Include file ops (path, operation), system commands, errors
- Avoid leaking sensitive data in logs

---

## Electron Renderer Process (Angular)

### Architecture & Patterns

- Lazy-loaded feature modules
- Optimize change detection
- Virtual scrolling for large datasets
- Use `trackBy` in ngFor
- Follow separation of concerns between component and service

### RxJS & Subscription Management

- Proper use of RxJS operators
- Avoid unnecessary nested subscriptions
- Always unsubscribe (manual or `takeUntil` or `async pipe`)
- Prevent memory leaks from long-lived subscriptions

### Error Handling & Exception Management

- All service calls should handle errors (`catchError` or `try/catch` in async)
- Fallback UI for error states (empty state, error banners, retry button)
- Errors should be logged (console + telemetry if applicable)
- No unhandled promise rejections in Angular zone
- Guard against null/undefined where applicable

### Security

- Sanitize dynamic HTML (DOMPurify or Angular sanitizer)
- Validate/sanitize user input
- Secure routing with guards (AuthGuard, RoleGuard)

---

## Native Integration Layer (AppleScript, Shell, etc.)

### Architecture

- Integration module should be standalone — no cross-layer dependencies
- All native commands should be wrapped in typed functions
- Validate input before sending to native layer

### Error Handling

- Timeout wrapper for all native commands
- Parse and validate native output
- Fallback logic for recoverable errors
- Centralized logging for native layer errors
- Prevent native errors from crashing Electron Main

### Performance & Resource Management

- Avoid blocking main thread while waiting for native responses
- Handle retries on flaky commands
- Limit concurrent native executions if needed
- Monitor execution time of native calls

### Security

- Sanitize dynamic script generation
- Harden file path handling passed to native tools
- Avoid unsafe string concatenation in command source

---

## Common Pitfalls

- Missing `await` → unhandled promise rejections
- Mixing async/await with `.then()`
- Excessive IPC between renderer and main
- Angular change detection causing excessive re-renders
- Memory leaks from unhandled subscriptions or native modules
- RxJS memory leaks from unhandled subscriptions
- UI states missing error fallback
- Race conditions from high concurrency API calls
- UI blocking during user interactions
- Stale UI state if session data not refreshed
- Slow performance from sequential native/HTTP calls
- Weak validation of file paths or shell input
- Unsafe handling of native output
- Lack of resource cleanup on app exit
- Native integration not handling flaky command behavior

---

## Review Checklist

1. ✅ Clear separation of main/renderer/integration logic
2. ✅ IPC validation and security
3. ✅ Correct async/await usage
4. ✅ RxJS subscription and lifecycle management
5. ✅ UI error handling and fallback UX
6. ✅ Memory and resource handling in main process
7. ✅ Performance optimizations
8. ✅ Exception & error handling in main process
9. ✅ Native integration robustness & error handling
10. ✅ API orchestration optimized (batch/parallel where possible)
11. ✅ No unhandled promise rejection
12. ✅ No stale session state on UI
13. ✅ Caching strategy in place for frequently used data
14. ✅ No visual flicker or lag during batch scan
15. ✅ Progressive enrichment for large scans
16. ✅ Consistent UX across dialogs

---

## Feature Examples (🧪 for inspiration & linking docs)

### Feature A

📈 `docs/sequence-diagrams/feature-a-sequence.puml`
📊 `docs/dataflow-diagrams/feature-a-dfd.puml`
🔗 `docs/api-call-diagrams/feature-a-api.puml`
📄 `docs/user-flow/feature-a.md`

### Feature B

### Feature C

### Feature D

### Feature E

---

## Review Output Format

```markdown
# Code Review Report

**Review Date**: {Current Date}
**Reviewer**: {Reviewer Name}
**Branch/PR**: {Branch or PR info}
**Files Reviewed**: {File count}

## Summary

Overall assessment and highlights.

## Issues Found

### 🔴 HIGH Priority Issues

- **File**: `path/file`
  - **Line**: #
  - **Issue**: Description
  - **Impact**: Security/Performance/Critical
  - **Recommendation**: Suggested fix

### 🟡 MEDIUM Priority Issues

- **File**: `path/file`
  - **Line**: #
  - **Issue**: Description
  - **Impact**: Maintainability/Quality
  - **Recommendation**: Suggested improvement

### 🟢 LOW Priority Issues

- **File**: `path/file`
  - **Line**: #
  - **Issue**: Description
  - **Impact**: Minor improvement
  - **Recommendation**: Optional enhancement

## Architecture Review

- ✅ Electron Main: Memory & Resource handling
- ✅ Electron Main: Exception & Error handling
- ✅ Electron Main: Performance
- ✅ Electron Main: Security
- ✅ Angular Renderer: Architecture & lifecycle
- ✅ Angular Renderer: RxJS & error handling
- ✅ Native Integration: Error handling & stability

## Positive Highlights

Key strengths observed.

## Recommendations

General advice for improvement.

## Review Metrics

- **Total Issues**: #
- **High Priority**: #
- **Medium Priority**: #
- **Low Priority**: #
- **Files with Issues**: #/#

### Priority Classification

- **🔴 HIGH**: Security, performance, critical functionality, crashing, blocking, exception handling
- **🟡 MEDIUM**: Maintainability, architecture, quality, error handling
- **🟢 LOW**: Style, documentation, minor optimizations
```