Skip to main content

​
Quick Start

Get Thrust running on your Mac in just a few minutes.

​
Prerequisites

Before you begin, make sure you have:
  • macOS 14.0+ (Sonoma or later)
  • Xcode 16.0+ with iOS 18 SDK
  • Apple Developer Account (for device testing)
  • Git installed

​
Installation

​
1. Clone the Repository

git clone https://github.com/Andrei-Kondrykau/thrust.git
cd thrust

​
2. Run Setup Script

The setup script will configure everything automatically: 
./Scripts/QUICK_SETUP.sh
This script will:
  • Create Secrets.plist from template
  • Install dependencies
  • Configure project settings
  • Verify Xcode installation

​
3. Configure Secrets (Optional)

If you want to use Connected Mode features, add your API keys to Secrets.plist: 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Bank integration (EU only) -->
    <key>GoCardlessSecretID</key>
    <string>your_gocardless_secret_id</string>
    <key>GoCardlessSecretKey</key>
    <string>your_gocardless_secret_key</string>
    
    <!-- Crypto wallet tracking -->
    <key>MoralisAPIKey</key>
    <string>your_moralis_api_key</string>
</dict>
</plist>
Ghost Mode works without any API keys! You only need these for Connected Mode features.

​
4. Open in Xcode

open Thrust.xcodeproj

​
5. Select Target Device

In Xcode:
  1. Select a simulator or connected device
  2. Choose Thrust scheme
  3. Press ⌘R to build and run

​
First Run

When you first launch Thrust:
  1. Welcome Screen - Choose your privacy mode
    • Ghost Mode - All data on-device (recommended for development)
    • Connected Mode - With cloud sync
  2. Create Profile - Set up your user profile
    • Name
    • Primary currency
    • Week start day
  3. Add First Account - Create your first account
    • Account type (Cash, Bank, etc.)
    • Name
    • Initial balance
  4. Done! - You’re ready to use Thrust

​
Development Workflow

​
Running the App

Simulator: 
# Build and run
⌘R in Xcode

# Or via command line
xcodebuild -scheme Thrust -destination 'platform=iOS Simulator,name=iPhone 15 Pro'
Device:
  1. Connect your iPhone/iPad
  2. Select it in Xcode
  3. Press ⌘R

​
Testing

Run all tests: 
⌘U in Xcode
Run specific test: 
xcodebuild test -scheme Thrust -only-testing:ThrustTests/SafeToSpendEngineTests

​
Code Quality

Run quality checks before committing: 
./Scripts/quality-check-fintech.sh
This checks:
  • SwiftLint violations
  • Build warnings
  • Test coverage
  • Localization completeness

​
Project Structure

Key directories to know: 
Thrust/
├── Features/              # Feature modules
│   ├── Dashboard/         # Main screen
│   ├── Transactions/      # Transaction management
│   ├── Accounts/          # Account management
│   └── ...
├── Models/                # SwiftData models
│   ├── Transaction.swift
│   ├── Account.swift
│   └── ...
├── Managers/              # Business logic
│   ├── NotificationManager.swift
│   ├── PrivacyManager.swift
│   └── ...
├── Components/            # Reusable UI
│   ├── Charts/
│   ├── UnifiedListRow/
│   └── ...
└── Design/                # Design system
    ├── Typography.swift
    ├── AppColors.swift
    └── ...

​
Common Tasks

​
Add a New Feature

  1. Create feature directory in Features/
  2. Add views, view models, and components
  3. Register in navigation
  4. Add tests

​
Add a New Model

  1. Create model in Models/
  2. Add @Model macro
  3. Update DataSchema.swift if needed
  4. Create migration if changing existing model

​
Add a New Screen

  1. Create view in appropriate feature directory
  2. Add to navigation in MainView.swift or sheet coordinator
  3. Add localization strings
  4. Test on different screen sizes

​
Debug Issues

SwiftData issues: 
// Enable verbose logging
UserDefaults.standard.set(true, forKey: "com.apple.CoreData.SQLDebug")
UI issues:
  • Use Xcode View Debugger (⌘⌥D while running)
  • Check console for SwiftUI warnings
  • Test on different devices/orientations
Performance issues:
  • Use Instruments (⌘I)
  • Check Time Profiler
  • Monitor memory usage

​
API Keys (Optional)

​
GoCardless (Bank Integration)

  1. Sign up at gocardless.com
  2. Create an app
  3. Get Secret ID and Secret Key
  4. Add to Secrets.plist
Supported countries: EU only (PSD2)

​
Moralis (Crypto Tracking)

  1. Sign up at moralis.io
  2. Create a project
  3. Get API key
  4. Add to Secrets.plist
Supported blockchains:
  • Ethereum, BSC, Polygon (EVM)
  • Solana
  • Bitcoin
  • TON
  • TRON
  • Cosmos
  • Polkadot

​
Troubleshooting

​
Build Fails

“Secrets.plist not found” 
# Run setup script
./Scripts/QUICK_SETUP.sh
“Swift version mismatch”
  • Update to Xcode 16.0+
  • Clean build folder (⌘⇧K)
“Signing error”
  • Select your development team in project settings
  • Enable “Automatically manage signing”

​
Runtime Issues

“App crashes on launch”
  • Check console for errors
  • Delete app and reinstall
  • Reset simulator
“SwiftData migration failed”
  • Delete app data
  • Or implement migration in DataSchema.swift
“UI not updating”
  • Check @Observable on view models
  • Verify @Query in views
  • Use @Environment correctly

​
Performance Issues

“App is slow”
  • Check for expensive computations in views
  • Use Task for async work
  • Profile with Instruments
“High memory usage”
  • Check for retain cycles
  • Use weak references where needed
  • Profile with Memory Graph Debugger

​
Next Steps

Now that you have Thrust running:

Features Overview

Explore all features in detail

Architecture

Understand the app architecture

Project Structure

Navigate the codebase

Contributing

Contribute to Thrust

​
Getting Help

  • GitHub Issues - Report bugs
  • GitHub Discussions - Ask questions
  • Code Comments - Most code is well-documented
  • CLAUDE.md - AI assistant instructions
Happy coding! 🚀