CodeCap Desktop Development

Development guidance for working on CodeCap Desktop, an Electron application that captures text from any screen region using OCR. Designed for developers, product owners, and project managers to capture and organize code snippets, acceptance criteria, and notes.

Project Context

CodeCap Desktop is an Electron-based productivity tool with:

Development Commands

When working on this project, use these commands:

Distribution uses electron-builder with configuration in `electron-builder.yml`.

Architecture Overview

Main Process (`src/main/main.js`)

The main process is the application orchestrator:

Window System

Four distinct window types:

1. **System Tray** - Lives in system tray, toggles emblem visibility

2. **Floating Emblem** - Small `CC` badge near cursor

3. **Vertical Toolbar** - Expandable panel with Codes/Cap/AI/Settings buttons

4. **Overlay Window** - Full-screen dimmed overlay for region selection

Services Layer (`src/main/services/`)

**Database (`db.js`)**

**OCR (`ocr/ocr-service.js`)**

**AI Client (`ai/ai-client.js`)**

**Share (`share.js`)**

Renderer Processes (`src/renderer/`)

Preload Bridge (`src/preload/index.js`)

Secure IPC bridge exposing methods to renderer contexts.

Data Storage

**User Data Directory** (platform-specific):

**Snippet Schema**:

```javascript

{

id: 'uuid',

title: 'string',

body: 'string',

category: 'code|acceptance-criteria|notes',

tags: ['array'],

createdAt: timestamp,

updatedAt: timestamp,

aiSummary: 'string',

aiTags: ['array'],

language: 'string'

}

```

Screen Capture Pipeline

Understanding the capture flow:

1. Global shortcut triggers capture mode

2. Overlay window covers target display

3. User selects region via drag gesture

4. desktopCapturer API screenshots entire display

5. Image cropped to selection bounds with scaling calculations

6. OCR processes cropped image buffer

7. Results presented in review modal

**Display Scaling Handling**:

Technical Patterns

**Window Management**:

**Code Style**:

**Key Dependencies**:

Development Guidance

When modifying CodeCap Desktop:

1. **Main Process Changes**: All window management and IPC handlers live in `src/main/main.js`

2. **Service Layer**: Keep business logic (OCR, DB, AI) in `src/main/services/`

3. **Renderer Changes**: Update corresponding `.html` and `.js` files in `src/renderer/`

4. **IPC Communication**: Add new channels via `src/preload/index.js` for security

5. **State Persistence**: Use JSON files in userData directory for settings/state

6. **Display Handling**: Test capture on HiDPI displays and multi-monitor setups

7. **Distribution**: Run `npm run dist` to verify packaging before releases

Common Tasks

**Adding a new IPC channel**:

1. Define handler in `src/main/main.js` via `ipcMain.handle()`

2. Expose method in `src/preload/index.js` via `contextBridge.exposeInMainWorld()`

3. Call from renderer via `window.api.methodName()`

**Modifying snippet schema**:

1. Update structure in `src/main/services/db.js`

2. Handle migration for existing `snippets.json` files

3. Update UI components in toolbar renderer

**Enhancing OCR**:

1. Modify `src/main/services/ocr/ocr-service.js`

2. Consider additional Tesseract language files

3. Test with various screen capture scenarios

**Improving AI features**:

1. Replace stubs in `src/main/services/ai/ai-client.js`

2. Integrate actual AI provider APIs

3. Update settings UI for provider configuration