The Problem

The repository intends to deliver a private, local-capable voice dictation alternative to subscription-based cloud apps. However, from a software architecture perspective, the codebase exhibits significant technical debt that risks long-term maintainability. The project faces the classic "craft over engineering" trade-off: functional and privacy-focused, but structurally unstable.

What This Does

Jarvis is a voice-powered AI assistant for macOS built with a React and Tailwind frontend (src/components, src/App.tsx). The core transcription engine is packaged via packages/whisper-addon, compiling C++ Whisper models for local STT. State and settings are centralized through src/core/logger (which 99 other modules depend on, importing 0) and src/services/app-settings-service.ts. The app supports offline Whisper/Parakeet models and optional Ollama LLM integration for rephrasing and command processing. The iOS directory contains duplicate SwiftUI source trees (ios/JarvisAI_Source/ vs ios/JarvisAI/), indicating parallel development branches.

How It Is Wired

Execution typically starts at src/main.ts, which orchestrates initialization via initializeJarvis. The internal call graph reveals src/core/logger as a high-blast-radius hub: 99 modules import it, it imports nothing, making changes here ripple widely. The project contains 10 files participating in circular import cycles (e.g., src/main.ts, src/input/push-to-talk-refactored.ts), which creates fragility during refactoring. Transcription flows transcribe -> handleTraditionalTranscription -> transcribeFromBuffer, writing to the filesystem via fs.writeFileSync. Notably, 1064 repeated 6-line blocks exist across iOS ContentView.swift and KeyboardView.swift files, violating the DRY principle. The test suite is minimal: 1 file against 213 source files.

How To Use It

Setup: Download the DMG from the releases page (Apple Silicon or Intel builds as documented in the README). Configuration: Local models (Whisper/tiny/base/small or Parakeet) are selected in Settings → Transcription. Ollama integration requires a separate Ollama install; models are pulled via terminal and selected in Settings → AI Models. API keys for Deepgram/Gemini are stored and managed in src/services/secure-api-service.ts. Running it: The application is launched as a macOS app bundle. There is no npm start or development server; the entry point for the built binary is the app bundle initializer, though the source entry is src/index.tsx.

# Example: Pulling an Ollama model (external to repo, documented in README)
ollama pull llama3

Real-World Use

A user holds the Fn key, speaks a request such as "Draft an email to my manager about the project delay," and releases the key. The push-to-talk-orchestrator captures audio, packages/whisper-addon transcribes it locally using the selected model, and if Ollama is enabled, the ollama-provider reformats the text or extracts intent. The cleaned text is then pasted into the active application via the text-output manager, all without data leaving the machine.

Code Health & Issues

  • HIGH - No CI/CD pipeline: 212 source files merge without an automated build/test gate (.github/ or CI config absent).
  • HIGH - Import cycles: 10 files participate in circular dependencies (e.g., src/main.ts, src/input/push-to-talk-refactored.ts), creating fragility for changes.
  • HIGH - Hub module instability: src/core/logger.ts is imported by 99 modules; changes here have high-blast-radius impact.
  • HIGH - Duplicated code: 1064 repeated 6-line blocks across iOS ContentView.swift and KeyboardView.swift files.
  • MEDIUM - Empty catch blocks: src/audio/paste-helper.ts and src/transcription/sherpa-model-downloader.ts silently discard errors.
  • MEDIUM - Test coverage gap: 1 test file against 213 source files (ratio 0.005); a green badge does not imply safety.

The Bottom Line

This is a capable, privacy-first dictation engine that successfully executes its core promise of local, subscription-free operation. However, the absence of CI, circular imports, and duplicated iOS logic represent significant technical debt. It is well-suited for a solo developer or small team needing immediate privacy, but an organization requiring stable, long-term maintenance would need to invest in cycle-breaking refactors and test expansion.