This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Loading actions...
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Career Compass is a privacy-first career exploration desktop application built as a hybrid Next.js/Electron app. It analyzes resumes locally using multiple LLM providers to suggest personalized career paths. The architecture prioritizes user privacy with local file processing and secure storage.
npm run dev # Start Next.js development server
npm run electron:dev # Start both Next.js and Electron (main development command)
npm run electron:dev-unsafe # Development with disabled web security for debugging
npm run build # Build Next.js static export
npm run electron:pack # Package Electron app for testing (no installer)
npm run electron:dist # Build production distributables for current platform
# Update version in package.json, commit, then:
git tag v0.x.x
git push origin v0.x.x # Triggers GitHub Actions multi-platform build
output: 'export')Located in lib/llm-providers.ts, implements a provider abstraction pattern:
LLMProvider) for all AI providersSupported providers:
Dual storage system in lib/settings-store.ts:
Desktop (Electron):
electron-store in user data directorysafeStorage with OS-native encryption (keychain/credential manager)Web (Fallback):
localStoragelocalStorage (less secure)Critical Implementation Detail: Settings store operations are async to handle IPC communication. Always use await when calling settingsStore.get(), settingsStore.set(), etc.
Located in lib/file-processors.ts with API routes in app/api/parsePdf/:
pdf-parse library (configured as external package in Next.js)mammoth library for Word document conversionElectron Security Hardening:
contextIsolation: true with secure IPC bridge (electron/preload.js)nodeIntegration: false and webSecurity: truePrivacy Design:
Between main and renderer processes via electron/preload.js:
// 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)
Two-stage LLM process in app/api/getCareers/route.ts:
ReactFlow Integration: Career suggestions rendered as interactive nodes in components/CareerNode.tsx with visualization in app/careers/page.tsx.
next.config.mjs)output: 'export' // Static export for Electron
serverComponentsExternalPackages: ['pdf-parse'] // External package handling
images: { unoptimized: true } // Required for static export
package.json build section)Career-Compass-{version}-{arch}.{ext} (no spaces)/.github/workflows/release.yml)v* tags (e.g., v0.2.0)Settings system supports environment variables as fallback:
OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, GOOGLE_API_KEYwindow.electronAPI.getEnvVar() in renderer processlib/settings-store.ts for precedence orderreact-hot-toast for user feedback/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)Connection testing implementation varies by provider:
GET /api/tags endpointGET /v1/models endpointPOST /v1/messages with minimal test requestGET /v1beta/models endpointAll connection tests include API key validation and environment variable fallback logic.