High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• spec/03-architecture.md
• AGENTS.md
• spec/README.md
• CLAUDE.md
• spec/10-ai-coding-method.md
• plans/active/cli-as-canonical-parakeet-surface.md

MacParakeet is designed as a local-first, fast, and private voice application specifically optimized for Apple Silicon Macs. The system architecture is built around a shared core logic library that powers both a high-fidelity SwiftUI macOS application and a versioned Command Line Interface (CLI) for automation and agentic workflows.

Sources: AGENTS.md:12-19, spec/README.md:5-7

The project adheres to a "local-first" posture, ensuring that audio capture and transcriptions remain on-device. It utilizes NVIDIA Parakeet TDT models running via the FluidAudio CoreML/ANE framework to achieve high-performance speech-to-text (STT) without requiring cloud processing for core functionality.

Sources: AGENTS.md:59-61, spec/README.md:73-77

System Structure and Core Modules

The repository is structured into distinct modules to separate concerns between business logic, view models, and user interfaces.

Module Hierarchy

• MacParakeetCore: The foundation library containing shared logic, including STT engines, database repositories, text processing pipelines, and service adapters. It is designed to be independent of SwiftUI view ownership.
• MacParakeetViewModels: Contains @Observable view models that encapsulate state and logic, allowing for testing independent of the graphical user interface.
• App Surface: The user-facing SwiftUI application (MacParakeet.app).
• CLI Surface: The public automation surface (macparakeet-cli) located in Sources/CLI/.

Sources: AGENTS.md:21-25, AGENTS.md:46-51, plans/active/cli-as-canonical-parakeet-surface.md:95-108

Dependency Flow Diagram

The following diagram illustrates the relationship between the core components and the dual product surfaces.

Data Persistence and Storage

MacParakeet utilizes SQLite via the GRDB toolkit for all local data persistence. The architecture follows a repository pattern, typically assigning one repository per database table to manage access.

Sources: AGENTS.md:54-55, spec/README.md:79

Component	Technology	Role
Database Engine	SQLite	Local-first, zero-config relational storage.
Access Layer	GRDB	Swift-native wrapper for type-safe database operations.
Schema Management	Repositories	Decoupled data access logic; one per table.
User Data	Local Files	Audio files and meeting artifacts stored in Application Support.

Sources: AGENTS.md:54-55, spec/README.md:79, CLAUDE.md:104-106

Audio and STT Pipeline

The audio pipeline is responsible for capturing sound from various sources and feeding it into the Speech-to-Text (STT) engine. The primary engine is NVIDIA Parakeet TDT 0.6B v3, which is accelerated by the Apple Neural Engine (ANE).

Capture Modes

The architecture supports three primary capture workflows:

1. System-wide Dictation: Real-time voice capture for text input.
2. File/Media Transcription: Batch processing of local files or remote media URLs.
3. Meeting Recording: Simultaneous capture of microphone and system audio via ScreenCaptureKit.

Sources: AGENTS.md:13-16, spec/README.md:180-185

STT Processing Flow

The STT runtime is managed by a centralized scheduler that handles inference slots and model warm-ups.

Technical Standards and Boundaries

The project maintains strict technical boundaries to ensure code quality and system reliability.

• Swift Concurrency: New I/O and asynchronous tasks MUST use async/await rather than completion handlers or Combine.
• UI Patterns: User interface buttons use .parakeetAction(...) and adhere to specific brand color disciplines (e.g., coral for moments of attention).
• Boundary Contracts: Public and semi-public interfaces (CLI JSON output, meeting artifact folders, recovery files) are governed by explicit contracts in spec/contracts/.

Sources: AGENTS.md:52-53, AGENTS.md:56-57, spec/README.md:43-46, CLAUDE.md:110-111

Conclusion

MacParakeet’s architecture emphasizes local performance and modularity. By centering the system on MacParakeetCore and the Apple Neural Engine, the project provides a robust foundation for both its native GUI and the macparakeet-cli, enabling high-performance voice workflows without compromising user privacy.

Sources: spec/03-architecture.md, plans/active/cli-as-canonical-parakeet-surface.md:95-108