# IPC Channel Documentation

This document describes all IPC (Inter-Process Communication) channels used in the Instructure Agent application.

## Naming Convention

**Standard Pattern:** `<domain>:<action>[-<resource>]`

- **Domain**: The feature area or tool (e.g., `docker`, `git`, `settings`)
- **Action**: The operation being performed (e.g., `get`, `set`, `install`, `update`)
- **Resource**: Optional, specific resource being acted upon (e.g., `status`, `config`)

**Examples:**
- `settings:get-all` - Get all settings
- `docker:install` - Install Docker
- `git-clone:get-status` - Get git clone status

## Channel Inventory (49 total)

### Actions (4 channels)
Manage protocol URL actions and history.

- `actions:get-all` - Get all actions
- `actions:get` - Get a specific action by ID
- `actions:delete` - Delete an action by ID
- `actions:clear` - Clear all actions

### App (1 channel)
Application-level operations.

- `app:get-version` - Get application version

### Artifactory (2 channels)
JFrog Artifactory configuration for Ruby gems.

- `artifactory:get-status` - Get Artifactory configuration status
- `artifactory:setup` - Configure Artifactory credentials

### Build & Run (2 channels)
Canvas LMS build and run operations.

- `build-run:get-status` - Get build/run status
- `build-run:build` - Build and run Canvas LMS

### Git Clone (6 channels)
Repository cloning operations.

- `git-clone:get-status` - Get clone status
- `git-clone:select-folder` - Open folder picker for clone location
- `git-clone:save-folder` - Save selected folder path
- `git-clone:clone` - Clone the repository
- `git-clone:reset` - Reset repository to clean state
- `git-clone:mark-configured` - Mark step as configured

### Git Config (2 channels)
Git user configuration.

- `git:get-status` - Get git config status (user.name, user.email)
- `git:update-config` - Update git config

### Inst CLI (2 channels)
Instructure CLI Docker image operations.

- `inst-cli:get-status` - Get inst-cli image status
- `inst-cli:build` - Build inst-cli Docker image

### Inst CLI Proxy (4 channels)
Local DNS resolver for inst-cli development.

- `inst-cli-proxy:get-status` - Get proxy status
- `inst-cli-proxy:create-docker-compose` - Create docker-compose override
- `inst-cli-proxy:start` - Start the proxy
- `inst-cli-proxy:stop` - Stop the proxy

### Inst Config (2 channels)
Inst CLI configuration file management.

- `inst-config:get-status` - Get inst config file status
- `inst-config:save` - Save inst config file content

### Onboarding (5 channels)
Setup wizard state and step management.

- `onboarding:get-state` - Get setup wizard state
- `onboarding:set-state` - Update setup wizard state
- `onboarding:get-steps` - Get all setup wizard steps
- `onboarding:validate-step` - Validate a specific step
- `onboarding:update-tray-icon` - Update tray icon based on step status

### Settings (2 channels)
Application settings management.

- `settings:get-all` - Get all application settings
- `settings:set` - Update a specific setting

### SSH Keys (4 channels)
SSH key generation and management.

- `ssh:get-status` - Get SSH key status
- `ssh:generate-keys` - Generate new SSH keys
- `ssh:select-public-key` - Open file picker for public key
- `ssh:read-public-key` - Read public key file content

### System (13 channels)
System tool installation and management (Docker, Homebrew, FRPC).

#### General
- `system:get-status` - Get overall system status

#### Docker (4 channels)
- `system:check-docker` - Check Docker installation status
- `system:install-docker` - Install Docker via Homebrew
- `system:update-docker` - Update Docker via Homebrew
- `system:reinstall-docker` - Reinstall Docker via Homebrew

#### Homebrew (4 channels)
- `system:check-homebrew` - Check Homebrew installation status
- `system:install-homebrew` - Install Homebrew
- `system:update-homebrew` - Update Homebrew
- `system:reinstall-homebrew` - Reinstall Homebrew

#### FRPC (4 channels)
- `system:check-frpc` - Check FRPC installation status
- `system:install-frpc` - Install FRPC via Homebrew
- `system:update-frpc` - Update FRPC via Homebrew
- `system:reinstall-frpc` - Reinstall FRPC via Homebrew

## Output Channels (Streaming)

These channels stream output during long-running operations. They follow the pattern: `<domain>:<operation>-output` or `<domain>:<operation>:output`.

### Docker Output
- `docker:install-output`
- `docker:update-output`
- `docker:reinstall-output`

### Homebrew Output
- `homebrew:install-output`
- `homebrew:update-output`
- `homebrew:reinstall-output`

### FRPC Output
- `frpc:install-output`
- `frpc:update-output`
- `frpc:reinstall-output`

### Inst CLI Output
- `inst-cli:build-output`

### Git Clone Output
- `git-clone:clone-output`
- `git-clone:reset-output`

### Inst CLI Proxy Output
- `inst-cli-proxy:start-output`
- `inst-cli-proxy:stop-output`

### Build & Run Output
- `build-run:output`

## Event Channels (Push Notifications)

These channels are used to push notifications from main to renderer.

- `action:added` - Notify when a new protocol URL action is added

## Naming Notes

### Current Consistency
The current naming is **already quite consistent** with the `<domain>:<action>` pattern. Most channels follow a clear, predictable structure.

### Minor Inconsistencies
The `system:*` namespace groups Docker, Homebrew, and FRPC operations under a single domain. An alternative pattern could separate these:
- `system:check-docker` → `docker:check-status`
- `system:install-docker` → `docker:install`
- `system:check-homebrew` → `homebrew:check-status`

However, this change would:
- Be a breaking change affecting multiple files
- Provide minimal clarity improvement
- Introduce migration risk

**Decision:** Keep current naming. The `system:` prefix clearly indicates these are system-level tool operations, and the current structure is intuitive and well-documented.

## Best Practices

### Adding New Channels
When adding new IPC channels:

1. **Follow the pattern**: `<domain>:<action>[-<resource>]`
2. **Use lowercase with hyphens**: `git-clone:get-status`, not `gitClone:getStatus`
3. **Be specific**: `get-status` is better than just `get`
4. **Group related operations**: Keep all Docker operations under `system:*-docker`
5. **Document output channels**: If streaming output, use `<domain>:<operation>-output`

### Deprecating Channels
When deprecating an IPC channel:

1. Add both old and new handlers
2. Log deprecation warnings when old channel is used
3. Update all call sites to use new channel
4. Remove old handler after migration is complete
5. Update this documentation

## Implementation Details

### Handler Registration
IPC handlers are organized into domain-specific modules:

- `src/main/ipc-handlers/settings-handlers.ts` - Settings and actions
- `src/main/ipc-handlers/system-handlers.ts` - Docker, Homebrew, FRPC
- `src/main/ipc-handlers/tool-handlers.ts` - Git clone, inst-config, proxy, build-run
- `src/main/ipc-handlers/setup-wizard-handlers.ts` - Onboarding, artifactory, inst-cli, git, SSH

### Preload API
All IPC channels are exposed to renderer processes through preload scripts:

- `src/preload/actions-preload.ts` - Actions API
- `src/preload/settings-preload.ts` - Settings API
- `src/preload/setup-wizard-preload.ts` - Setup wizard API

### Type Safety
All IPC channels are type-checked through TypeScript interfaces defined in:
- `src/renderer/types.ts` - Shared type definitions

## Migration History

### v1.0.0 - Initial Implementation
- Established 49 IPC channels with consistent naming
- Organized handlers into domain-specific modules
- Created preload API abstractions

### Future Considerations
- Consider migrating `system:*-docker/homebrew/frpc` to dedicated domains if the number of operations grows significantly
- Standardize output channel naming (choose between `-output` or `:output` suffix)
