kartonche

A modern, open-source iOS app for managing loyalty cards.

Overview

kartonche (картонче, "small card" in Bulgarian) is a native iOS app that helps you digitize and organize all your loyalty cards. No more fumbling through your wallet at checkout - just open the app, select your card, and scan.

Key Features

• ✅ Barcode Generation - Generate QR, Code128, Code 39, EAN-13, EAN-8, UPC-E, PDF417, Aztec, DataMatrix, and Interleaved 2 of 5 barcodes
• ✅ Barcode Scanning - Scan physical cards with your camera or photos using VisionKit
• ✅ Quick Access - Display barcodes instantly with brightness boost and screen wake
• ✅ Quick Scan - Snap a photo or pick from library to auto-extract barcode and card color
• ✅ Card Photos - Attach and crop photos for your cards
• ✅ Smart Search - Search and sort cards by name, store, or recent usage
• ✅ Localized - Full Bulgarian translation with English as base language
• ✅ Widgets - Home screen, lock screen, and Control Center widgets for quick access
• ✅ Apple Wallet - Generate Wallet passes for all supported barcode types
• ✅ iCloud Sync - CloudKit-based sync across your devices
• ✅ Spotlight Search - Cards indexed and searchable from iOS search
• ✅ Siri Shortcuts - App Intents for showing cards, generating barcodes, and searching
• ✅ Deep Linking - kartonche:// URL scheme for card access and Quick Scan
• ✅ Location Awareness - Get notified when near stores with your saved cards
• ✅ Expiration Tracking - Track card expiration dates with reminder notifications
• ✅ Export/Import - Share cards via AirDrop or save to files
• 💾 Local Storage - SwiftData-based storage (no cloud account required)

Quick Start

First time setup:

git clone https://github.com/zbrox/kartonche.git
cd kartonche
mise trust
mise run build

Daily development:

mise run dev              # Clean + build + test
mise run test             # Run tests
mise run ci               # Full CI check before commit

Open in Xcode simulator or connect an iOS 26.2+ device to test camera scanning.

Getting Started

Prerequisites

• macOS with Xcode 26.2+
• iOS 26.2+ device or simulator
• mise (optional but recommended)

Installation

1. Clone the repository:

git clone https://github.com/zbrox/kartonche.git
cd kartonche

2. Trust the mise configuration:

mise trust

3. Build and run:

mise run build

Or open kartonche.xcodeproj in Xcode and run.

Development

Using mise Tasks

We use mise for task automation:

# Build and test
mise run build            # Build the app (Debug)
mise run test             # Run unit tests
mise run test-ui          # Run UI tests
mise run test-all         # Run all tests (unit + UI)
mise run clean            # Clean build artifacts
mise run check            # Clean build and show all warnings/errors
mise run check-i18n       # Check localization completeness
mise run dev              # Clean + build + test

# Release and distribution
mise run changelog-preview    # Preview unreleased changes
mise run changelog-update     # Update CHANGELOG.md
mise run release              # Prepare a new release (bump version)
mise run tag-release          # Tag release and generate changelog
mise run archive              # Archive the app for distribution
mise run testflight           # Bump build, archive, upload to TestFlight

# CI workflow
mise run ci                   # Full CI check

Project Structure

kartonche/
├── AGENTS.md              # Guidelines for AI coding agents
├── ARCHITECTURE.md        # Technical architecture documentation
├── CHANGELOG.md           # Version history (auto-generated)
├── mise.toml              # Development task configuration
├── .mise/tasks/           # Individual task scripts
├── kartonche/             # Main app code
│   ├── Models/            # SwiftData models
│   ├── Views/             # SwiftUI views and components
│   ├── Utilities/         # Helper classes (barcode, brightness, permissions)
│   ├── Resources/         # Localizable.xcstrings
├── action/                # App Action extension
├── quicklook/             # QuickLook preview extension
├── widget/                # Home screen, lock screen, and control widgets
├── kartoncheTests/        # Unit tests
├── kartoncheUITests/      # UI tests
└── Scripts/               # Build scripts
    └── generate-about-icon.sh  # Xcode build phase for app icon

Documentation

• AGENTS.md - Coding guidelines, localization rules, commit conventions
• ARCHITECTURE.md - Technical decisions, data models, architecture patterns
• CHANGELOG.md - Version history (auto-generated from commits)

Contributing

We welcome contributions!

Code Contributions

1. Read AGENTS.md for coding guidelines
2. Follow conventional commits format
3. Write tests for new features (CI enforces all tests passing)
4. Run mise run test before committing
5. Ensure Bulgarian localization uses neutral forms (not imperatives)

Testing

We maintain comprehensive test coverage:

# Run unit tests
mise run test

# Run UI tests
mise run test-ui

# Run all tests
mise run test-all

# Full CI check (build + test)
mise run ci

Continuous Integration

GitHub Actions automatically:

• Runs unit tests on all PRs and main branch pushes

See .github/workflows/ for workflow definitions.

Technology Stack

• Language: Swift 6.2+
• Framework: SwiftUI + SwiftData (iOS 26.2+)
• Barcode: VisionKit (scanning) + Core Image (generation)
• Storage: SwiftData with optional iCloud sync (CloudKit private database)
• Localization: String Catalogs (English base, Bulgarian translation)
• Testing: Swift Testing framework
• Dependencies: Minimal dependencies: swift-crypto, swift-certificates, ZIPFoundation + native Apple frameworks

License

MIT License - See LICENSE file for details.

Acknowledgments

Thanks to early testers and friends who provided feedback.

---

Status: Released | Version: 2026.03.1 | Platform: iOS 26.2+