BlockBuddy

Your Safe Entry into Crypto — Education, Security, and Confidence powered by AI.

BlockBuddy is a native iOS app (iOS 17+, SwiftUI) that helps beginners understand cryptocurrency through bite-sized lessons, interactive quizzes, gamification, AI-powered explanations, and scam awareness training.

🎯 Vision

Make cryptocurrency easy, safe, and understandable for everyday people. Instead of focusing on trading or speculation, BlockBuddy focuses on education, security, confidence, and simple explanations.

🧠 Core Features

Feature	Description
Daily Mini Lessons	30–90 second crypto lessons, one concept at a time
Interactive Quizzes	Quick quizzes with XP rewards and streaks
AI Explain	Paste wallet popups or transaction text — AI explains in simple language
Scam Awareness	Fake vs real wallet examples, phishing detection, security simulations
Gamification	XP, streaks, badges, levels (Beginner → Intermediate → Expert)
Push Notifications	Daily facts, streak reminders, motivational nudges
Widget	Home screen widget showing current streak

🏗 Architecture

MVVM + Clean Architecture

View (SwiftUI)  ────────  ViewModel (@Observable)  ────────  UseCase
       ▲                         │                              │
       │                         ▼                              ▼
   Renders UI             Holds UI state                 Business Logic
                          Calls UseCases                 Single Responsibility
                                                                 │
                                                                 ▼
                                                          Repository
                                                              │
                                              ┌───────────────┴───────────────┐
                                              ▼                               ▼
                                        Data Source                      Data Source
                                         (Remote)                         (Local)
                                          │                                 │
                                    Firestore                          Core Data

📁 Project Structure

BlockBuddy/
  ├── App/
  │   ├── BlockBuddyApp.swift       // @main entry point
  │   ├── AppView.swift             // Root tab navigation
  │   └── AppState.swift            // Central state management
  ├── Core/
  │   ├── AppIntents/               // Siri shortcuts
  │   ├── Auth/                     // Sign in with Apple + Email
  │   ├── Data/                     // Repositories + models
  │   ├── Models/                   // Domain models
  │   ├── Networking/               // URLSession + cert pinning
  │   ├── Notifications/            // Push + local notifications
  │   ├── Persistence/              // Core Data stack
  │   ├── Security/                 // Jailbreak detection
  │   └── Services/                 // AI, OCR, Keychain, StoreKit, etc.
  ├── DesignSystem/
  │   ├── DesignSystem.swift         // Colors, typography, tokens
  │   └── Components/               // Reusable SwiftUI views
  ├── Features/
  │   ├── AIExplain/                // AI transaction explanation
  │   ├── Admin/                    // Lesson draft review
  │   ├── Auth/                     // Email sign-in
  │   ├── Home/                     // Main learning feed
  │   ├── Lessons/                  // Lesson detail view
  │   ├── Onboarding/               // First-time experience
  │   ├── Premium/                  // Paywall & subscriptions
  │   ├── Profile/                  // User progress & stats
  │   ├── Quiz/                     // Interactive quizzes
  │   └── ScamAwareness/            // Scam training scenarios
  ├── NotificationService/          // Rich push extension
  ├── Resources/
  │   ├── Assets.xcassets           // App icon, accent color
  │   ├── en.lproj/                 // English localization
  │   └── sv.lproj/                 // Swedish localization
  ├── Tests/
  │   ├── UnitTests/                // XCTest unit tests
  │   └── UITests/                  // XCUITest UI tests
  └── Widget/                       // WidgetKit extension

🛠 Tech Stack

Technology	Purpose
Swift 5.10+	Primary language
SwiftUI	Declarative UI framework
SwiftData	Local persistence
Core Data	Legacy persistence layer
Combine	Reactive data bindings
VisionKit	On-device OCR for screenshots
StoreKit 2	In-app purchases
Keychain	Secure token storage
UserNotifications	Push + local notifications
WidgetKit	Home screen widgets
AppIntents	Siri shortcuts
Firebase	Auth, Firestore, FCM, Crashlytics

📋 Requirements

Xcode 16+
iOS 17.0+
Swift 5.10+
CocoaPods: Not used — all dependencies via Swift Package Manager (SPM)

🚀 Setup

1. Clone

git clone https://github.com/Rizgart/BlockBuddy.git
cd BlockBuddy

2. Open in Xcode

open BlockBuddy.xcodeproj

3. SPM Dependencies

SPM resolves automatically. Packages:

firebase-ios-sdk (Auth, Core, Firestore, Messaging)
Lottie (animations)
SDWebImageSwiftUI (image caching)
KeychainAccess (keychain wrapper)

4. Firebase Setup (optional)

Create a project at Firebase Console
Download GoogleService-Info.plist
Add it to the BlockBuddy/ folder in Xcode
The app uses Firebase for: Auth, Firestore (lessons), FCM (push)

5. Server (optional AI proxy)

cd Server
cp .env.example .env
# Edit .env with your OpenAI API key
npm install
node src/server.js

The server proxies OpenAI GPT-4o requests. The iOS app uses the local AIExplanationService by default; configure ServerURL in the service to point to your server.

6. Run

Select the BlockBuddy scheme, choose an iOS 17 simulator, and press ⌘R.

🧪 Tests

# Run unit tests
xcodebuild test -project BlockBuddy.xcodeproj -scheme BlockBuddy \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

# Run UI tests
xcodebuild test -project BlockBuddy.xcodeproj -scheme BlockBuddyUITests \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

To add test targets in Xcode:

File → New → Target
Select Unit Testing Bundle (name: BlockBuddyUnitTests)
Select UI Testing Bundle (name: BlockBuddyUITests)
Add the existing test files to each target:
- Tests/UnitTests/AppStateTests.swift → BlockBuddyUnitTests
- Tests/UITests/BlockBuddyUITests.swift → BlockBuddyUITests

🎨 Design System

Primary: #1A3A5C (dark navy)
Accent: #F39C12 (gold/orange — XP, streaks)
Background: #0A0A1A (near-black)
Font: SF Pro (system font)
Dark mode primary, light mode supported

🔐 Security

All tokens stored in Keychain (never UserDefaults)
Certificate pinning via PinnedURLSession
On-device OCR — screenshots never leave the device raw
Jailbreak detection
App Transport Security (ATS) enforced — HTTPS only

📱 App Store

Category: Education
Bundle ID: com.blockbuddy.app
Minimum iOS: 17.0
Orientation: Portrait only
Languages: English, Swedish

📊 Gamification System

XP per completed lesson and quiz
Daily streaks with local notification reminders
Levels: Beginner → Intermediate → Expert
Badges: First Lesson, 7-Day Streak, Scam Spotter
Widget showing current streak on home screen

🚦 Monetization

Tier	Features
Free	Daily lessons, basic quizzes, 3 AI explanations/day
Premium	Unlimited AI, scam detector, wallet risk analysis, personalized AI tutor

📄 License

👤 Author

Nozad Teimouri

“The safest way to start crypto.”