Career Compass Development Assistant

Expert assistant for working with Career Compass, a privacy-first career exploration desktop application built as a hybrid Next.js/Electron app.

Project Context

Career Compass analyzes resumes locally using multiple LLM providers to suggest personalized career paths. The architecture prioritizes user privacy with local file processing and secure storage.

Technology Stack

Development Commands

Starting Development

```bash

npm run dev # Next.js development server only

npm run electron:dev # Full Electron + Next.js (primary dev command)

npm run electron:dev-unsafe # Debug mode with disabled web security

```

Building

```bash

npm run build # Build Next.js static export

npm run electron:pack # Package Electron app for testing

npm run electron:dist # Build production distributables

```

Release Process

```bash

Update version in package.json, commit changes, then:

git tag v0.x.x

git push origin v0.x.x # Triggers GitHub Actions multi-platform build

```

Architecture Guidelines

1. Multi-Provider LLM System

**Location**: `lib/llm-providers.ts`

**Supported Providers**:

**Connection Testing**:

2. Settings and Storage Architecture

**Location**: `lib/settings-store.ts`

**CRITICAL**: All settings store operations are async to handle IPC communication. Always use `await`.

**Desktop (Electron)**:

**Web (Fallback)**:

**Environment Variables**:

3. File Processing Pipeline

**Location**: `lib/file-processors.ts`, `app/api/parsePdf/`

4. Security Architecture

**Electron Security Hardening**:

**Privacy Design**:

5. IPC Communication Pattern

**Location**: `electron/preload.js`

```javascript

// Settings operations

window.electronAPI.store.get(key, defaultValue)

window.electronAPI.store.set(key, value)

// Secure storage for API keys

window.electronAPI.secureStorage.setPassword(service, password)

window.electronAPI.secureStorage.getPassword(service)

// Model management

window.electronAPI.models.getOllamaModels(baseURL)

window.electronAPI.models.testConnection(provider, config)

```

6. Career Generation Workflow

**Location**: `app/api/getCareers/route.ts`

Two-stage LLM process:

1. **Initial Analysis**: Resume + context → 6 career suggestions with basic info

2. **Detailed Analysis**: Each career → comprehensive roadmap, skills analysis, timeline

**Visualization**: ReactFlow integration in `components/CareerNode.tsx` and `app/careers/page.tsx`

Build Configuration

Next.js Configuration (`next.config.mjs`)

Electron Builder

GitHub Actions

File Structure

```

/app/* - Next.js App Router pages and API routes

/lib/* - Core business logic and utilities

/components/* - React components (UI components in /components/ui/)

/electron/* - Desktop-specific code (main process and preload script)

```

Error Handling

Implementation Instructions

When working on Career Compass:

1. **Always await settings store operations** - They use IPC and are async

2. **Test in both web and desktop modes** - Use `npm run dev` and `npm run electron:dev`

3. **Respect privacy-first design** - Keep file processing local

4. **Follow security patterns** - Use secure storage for sensitive data

5. **Support multiple LLM providers** - Follow the provider abstraction pattern

6. **Handle connection testing** - Implement appropriate health checks for each provider

7. **Use toast notifications** - Provide clear user feedback for all operations

8. **Check environment variables** - Support fallback configuration via env vars

Common Tasks

Adding a New LLM Provider

1. Add provider configuration to `lib/llm-providers.ts`

2. Implement `LLMProvider` interface

3. Add connection test endpoint logic

4. Update UI to include new provider option

5. Document environment variable support

Updating File Processing

1. Modify parser in `lib/file-processors.ts`

2. Update API route in `app/api/parsePdf/`

3. Add client-side validation

4. Test with various file formats

Modifying Career Analysis

1. Update prompts in `app/api/getCareers/route.ts`

2. Adjust two-stage workflow if needed

3. Update ReactFlow visualization in `components/CareerNode.tsx`

4. Test with different resume inputs

Release New Version

1. Update version in `package.json`

2. Commit all changes

3. Create and push version tag: `git tag v0.x.x && git push origin v0.x.x`

4. Monitor GitHub Actions build

5. Verify release artifacts on GitHub