Minuta Technical Documentation

Website: https://minuta.tools

Navigation

Project Overview

Minuta is a native multiplatform (macOS/iOS) time tracking app using local JSON storage (iCloud-ready architecture).

Quick Start

# Build and test (always run tests when building)
cd Shared && swift build && swift test

# Full build with tests
cd Shared && swift test && cd ../Minuta && xcodebuild -scheme Minuta -destination 'platform=iOS Simulator,name=iPhone 17' -quiet build

# Open in Xcode
open Minuta/Minuta.xcodeproj

Quick Links

Architecture

Models

Services

UI Components

Testing

Integrations

Development Log

Key Components

Views

  • ContentView - Single unified view (no tabs) with all sections
  • SettingsSheet - Modal with tags, data folder, import/export options
  • HistorySection - Date range filtering with records grouped by day
  • DateRangePickerView - Date preset buttons + From/To pickers
  • TagFilterView - Tag filter toggle buttons with FlowLayout
  • RunningTimersSection - Active timers section
  • TodaySectionView - Today’s records with soft delete
  • RunningTimerEditor - Inline editor for running timers
  • EditableRecordRow - Completed record with inline edit mode
  • DeletionToastView - Toast notification for deleted records with undo
  • FlowLayout - Custom Layout for wrapping elements (like CSS flex-wrap)

Services

  • AppState - Shared state management via @EnvironmentObject
  • StorageLocationManager - User folder selection with security-scoped bookmarks
  • ImportService - HEY CSV import
  • ExportService - CSV export
  • ReportService - PDF/SVG/PNG report generation with charts
  • SVGReportRenderer - Pure Swift SVG generation (no JS)

Utilities

  • DurationFormatter - Time interval formatting (timer, compact, CSV formats)
  • TagColorGenerator - Deterministic OKLCH-based tag colors from names
  • OKLCH - Color space conversion (sRGB to OKLCH)
  • CSVParser - CSV parsing and field escaping
  • StringExtensions - XML escaping for SVG generation
  • Logger - OSLog wrapper with app categories

App Intents

  • StartTimerIntent - Shortcuts: start timer with optional tag/comment
  • StopTimerIntent - Shortcuts: stop all running timers

Project Structure

Minuta/                # iOS + Mac Catalyst Xcode project
  Sources/             # SwiftUI views and app code
    Services/          # StorageLocationManager
    Views/             # All UI components
  project.yml          # XcodeGen config
Shared/                # Swift Package (models + services)
  Sources/MinutaShared/
    Models/            # Tag, TimeRecord, ExportOptions, ReportData
    Services/          # FileStorageService, ExportService, ImportService, TimeTrackingService, ReportService, SVGReportRenderer
    Utilities/         # DurationFormatter, TagColorGenerator, OKLCH, CSVParser, StringExtensions, Logger
docs/                  # Documentation