BreakCount Documentation

Technical documentation for the BreakCount Flutter app — architecture, services, themes, achievements, personas, widgets, AI scan, live activity, and nearby.

Quick Links

• breakcount.tech — project website
• Google Play — download the app
• GitHub — source code

Architecture Overview

Project Structure

lib/
├── app/                    # App-level config
│   ├── constants.dart      # Colors, spacing, StorageKeys
│   ├── routes.dart         # Named route definitions
│   ├── theme.dart          # MaterialApp theme builder
│   ├── theme_preset.dart   # ThemePreset model + AppThemeController
│   └── persona_theme_ext.dart  # BuildContext extension for persona tint
├── screens/                # Full-page UI (tabs, settings, review, etc.)
├── widgets/                # Reusable UI components
├── services/               # Business logic, platform channels, storage
├── data/                   # Static data (achievements, personas, school data)
├── models/                 # Data models (Schedule, Subject, Exam, etc.)
├── utils/                  # Helpers (debug_log)
└── main.dart               # Entry point, initialization, BreakCountApp widget

State Management

BreakCount uses a lightweight approach — no external state management package:

• ValueNotifier<T> for reactive state (theme, persona tint, streak)
• StorageService (SharedPreferences wrapper) for persistence
• setState() in StatefulWidgets for local UI state
• Listeners wired in main.dart for cross-cutting concerns

Data Flow

User action → Service method → StorageService.save() → ValueNotifier.value = x
                                                              ↓
                                                    Listeners fire
                                                              ↓
                                              Widget rebuilds / side effects
                                              (e.g., WidgetService.update())

Initialization Order (main.dart)

1. WidgetsFlutterBinding.ensureInitialized()
2. Firebase init (Core, Crashlytics, Analytics)
3. StorageService.init() — loads SharedPreferences
4. AppThemeController.init() — restores saved theme
5. AchievementService.init() — loads unlock state
6. StreakService.init() + recordOpen() — daily streak
7. PersonaService.init() — restores active persona
8. Cross-cutting listeners wired (achievement→widget, persona→widget, theme→widget, streak→achievement)
9. Notifications, FCM, widget update (fire-and-forget)
10. runApp(BreakCountApp(...))

Key Patterns

• Fire-and-forget: Non-critical operations (widget updates, analytics, auto-backup) never block startup.
• Graceful degradation: Every service wraps platform calls in try/catch; failures are logged, never propagated.
• Additive architecture: New features (themes, personas, achievements) plug into existing notifier/listener infrastructure without rewrites.

Services Reference

All services live in lib/services/. They are static-method classes (no instantiation needed) unless noted.

Core Services

Feature Services

Platform Services

AI Services

Utility Services

Theme System

BreakCount supports 17 theme presets. 6 are always available; 11 unlock via daily streak milestones or achievement triggers.

ThemePreset Model

class ThemePreset {
  final String id;
  final String name;
  final String emoji;
  final bool dark;
  final Color bgDeep;       // Scaffold background
  final Color bgDark;       // Elevated background
  final Color bgSurface;    // Card/surface background
  final Color primary;      // Primary accent
  final Color gradA, gradB; // Decorative gradient
  final Color surfaceBorder;
  final Color? textPrimary; // Override (null = default)
  final double cardOpacity;
}

Default Presets (Always Unlocked)

Unlockable Presets

AppThemeController

Global singleton managing the active theme:

• AppThemeController.notifier — ValueNotifier<ThemePreset>, UI listens to this
• AppThemeController.personaTintNotifier — persona accent color overlay
• AppThemeController.init(savedId) — restores from storage
• AppThemeController.setTheme(preset) — switches + persists

Widget Integration

When the theme changes, main.dart's listener calls WidgetService.update(), which writes hex color strings to HomeWidget SharedPreferences. The Android BreakCountWidgetProvider reads these and applies them via RemoteViews.setInt(...).

Adding a New Theme

1. Add a static const ThemePreset in theme_preset.dart
2. Add it to the all list
3. Add an UnlockRequirement entry in unlock_service.dart
4. The theme picker and widget system pick it up automatically

Achievements & XP System

100+ achievements across 8 categories, with an XP/level system and daily quests.

Achievement Model

class Achievement {
  final String id;
  final String name;
  final String description;
  final IconData icon;
  final AchievementCategory category;
  final AchievementRarity rarity;
  final int xp;              // XP granted on unlock
  final bool secret;         // Hidden until unlocked
}

Categories

schoolProgress, mondayClub, examsSchedule, breakMilestones, powerUser, streaks, themes, personas

Rarities & XP

XP / Level System

Thresholds: L1=0, L2=200, L3=600, L4=1500, L5=3500, L6=7000, L7=12000, L8=20000, L9=35000, L10=60000

Daily Quests

3 quests per day, deterministically seeded by date + install ID. ~20 quest templates (e.g., open_schedule_tab, tap_countdown_5x, change_persona). Completion grants XP; some high-tier quests unlock themes/personas. Reset at local midnight.

Milestone Helpers

AchievementService exposes helpers that other services call:

• onStreakMilestone(int days) — called by StreakService
• onThemeUnlocked(String id) — called by UnlockService
• onPersonaUnlocked(String id) — called by PersonaService
• onStudySessionLogged() — called by StudyLogService
• onAchievementCountChanged() — self-referential (hunter ladder)

Adding Achievements

1. Add entry to lib/data/achievements_data.dart with unique id, category, rarity, XP
2. Add unlock trigger in the appropriate service helper
3. Run test/achievements_data_test.dart to verify no duplicate IDs

Personas

30 personas, each with a unique emoji, tint color, and full copy palette. The active persona affects app-wide text, colors, confetti, widgets, and weekly recaps.

Persona Model

class Persona {
  final String id;
  final String name;
  final String emoji;
  final Color tint;          // Accent color override
  final bool isDefault;      // Always unlocked
}

Copy System

Copy is keyed by (personaId, slot). Slots include:

• countdown_far — 60+ days
• countdown_mid — 15–60 days
• countdown_close — 2–15 days
• countdown_imminent — 0–2 days
• break_reveal — break just started
• recap_intro — weekly recap opener
• greeting — app open

Base Personas (Always Unlocked)

Unlockable Personas

26 additional personas unlock via streak milestones and achievement triggers, registered in UnlockService. Includes: Ghost 👻, Sage 🧙, Nerd 🤓, Tired 🥱, Ice 🧊, Philosopher 🧐, Volcano 🌋, Sloth 🦥, Moon 🌙, Phoenix 🦅, Jester 🃏, Hacker 💻, Pirate 🏴‍☠️, Robot 🤖, and more.

PersonaService

• PersonaService.instance — singleton
• currentNotifier — ValueNotifier<Persona>, drives UI rebuilds
• setPersona(id) — switches active persona, updates tint notifier, persists
• init() — restores from storage

Persona Tint Integration

AppThemeController.personaTintNotifier is updated whenever the persona changes. The MaterialApp rebuilds with the new tint via persona_theme_ext.dart's BuildContext extension.

Adding a Persona

1. Add entry to lib/data/personas_data.dart
2. Add copy entries for all slots in lib/data/persona_copy.dart
3. Add unlock condition in lib/services/unlock_service.dart
4. Run test/persona_copy_test.dart to verify all slots are covered

Home Screen Widgets

Four widget sizes (2×1, 2×2, 4×1, 4×2) powered by native Android AppWidgetProvider + the home_widget Flutter package.

Architecture

Flutter (WidgetService.update())
    ↓ writes key-value pairs
HomeWidget SharedPreferences
    ↓ read by
Android BreakCountWidgetProvider (Kotlin)
    ↓ applies to
RemoteViews → AppWidgetManager.updateAppWidget()

Data Payload

Update Triggers

WidgetService.update() is called on app startup, when the theme changes, when the persona changes, when an achievement unlocks, and on background widget interaction.

Layout Files

• breakcount_widget_2x1.xml — horizontal pill
• breakcount_widget_2x2.xml — square card with progress ring
• breakcount_widget_4x1.xml — wide bar
• breakcount_widget_4x2.xml — wide card

AI Timetable Scan & Offline OCR

Offline-first timetable import: ML Kit OCR runs locally first, cloud providers are only called as a fallback.

Flow

User takes photo
    ↓
AiScheduleService.parseImage(file, apiKey)
    ↓
┌─ OcrTimetableParser.parse(file) ─── offline pre-pass
│   ├─ ML Kit TextRecognizer
│   ├─ Grid detection (rows by Y-coordinate)
│   ├─ Day column detection (header tokens)
│   ├─ Subject matching (canonical suggestions)
│   └─ Confidence scoring
│
├─ If confidence ≥ 0.6 AND entries ≥ 20 → return (isOfflineOcr: true)
│
└─ Else fall through to cloud provider:
    ├─ Groq Llama 4 (if key starts with gsk_)
    └─ Cloudflare Worker proxy (5 free/day, no key needed)
        ↓
AiReviewScreen (edit/delete entries per day)
    ↓
ScheduleService.save()

Offline OCR Algorithm

1. Run TextRecognizer(script: latin) on the image
2. Flatten recognized blocks into lines with bounding box coordinates
3. Group lines into rows by Y-coordinate (tolerance = 0.7× avg line height)
4. Detect day columns from header row (Mon/Tue/Wed/Thu/Fri in multiple languages)
5. Walk data rows, match text against country's canonical subject list
6. Assign each match to nearest day column
7. Deduplicate by (subject, day, startTime)

Confidence Scoring

confidence = entryScore × 0.6 + daysScore × 0.25 + subjectHitRate × 0.15

entryScore     = entries found / 20 (clamped 0–1)
daysScore      = distinct days covered / 5
subjectHitRate = matched entries / total recognized lines

Threshold: ≥ 0.6 confidence AND ≥ 20 entries → skip cloud call

Cloud Providers

• Groq Llama 4 — endpoint: api.groq.com/openai/v1/chat/completions, model: meta-llama/llama-4-scout-17b-16e-instruct. Free key from console.groq.com.
• Worker Proxy — endpoint: breakcount-ai.breakcount.workers.dev. Rate limit: 5 scans/day per device ID. No API key required.

Review Screen

AiReviewScreen shows entries day-by-day (Mon→Fri stepper). Features: edit subject name with autocomplete, pick start/end time, cycle color, swipe to delete, add new entries, and a green "Parsed offline" banner when isOfflineOcr is true.

Lock-Screen Live Activity

Android 14+ foreground service that shows a persistent break countdown notification on the lock screen. Uses Chronometer for battery-efficient live ticking.

Architecture

Flutter (LiveActivityService)
    ↓ MethodChannel 'com.breakcount/live_activity'
MainActivity.kt (channel handler)
    ↓ startForegroundService / stopService
BreakCountdownService.kt
    ↓ reads widget data from HomeWidget SharedPreferences
    ↓ builds Notification with Chronometer
Lock screen / notification shade

Method Channel API

Channel: com.breakcount/live_activity

BreakCountdownService (Kotlin)

• Foreground service type: specialUse
• Notification channel: breakcount_countdown (IMPORTANCE_LOW)
• Ongoing, silent, public visibility with Chronometer counting down to break start
• Handler posts every 15 minutes to refresh notification data

Permissions

• FOREGROUND_SERVICE — base permission
• FOREGROUND_SERVICE_SPECIAL_USE — required for specialUse type on API 34+
• POST_NOTIFICATIONS — required to show the notification

Nearby / Mesh System

BreakCount uses Android Nearby Connections (Bluetooth) for peer-to-peer features: schedule sharing, Vibe Beacon, and achievement compare.

Discovery Flow

startDiscovery() → onPeerFound callback
    ↓
User taps peer card
    ↓
requestConnection() → onConnectionEstablished
    ↓
sendPayload(data) ↔ receivePayload(data)
    ↓
disconnect()

Handshake Payload

{
  "type": "handshake",
  "name": "Anonymous Student",
  "persona_id": "hype",
  "persona_emoji": "🔥",
  "subject_count": 12,
  "entry_count": 35,
  "unlocked_achievement_ids": ["streak_7", "first_exam", ...]
}

Features

Schedule Copy

Peer card shows subject/entry count. "Copy" button pulls their schedule entries to your device. Merge/replace dialog if you already have entries.

Vibe Beacon

Long-press Vibe card → radar overlay. Groups discovered peers by persona. Real-time discovery while overlay is open.

Achievement Compare

Computes three sets from the handshake payload: Both have (intersection), Only mine, and Only theirs. Displayed as a bottom sheet from the nearby users screen.

Shake to Share

ShakeService detects 20 m/s² threshold. Opens share overlay when both devices shake simultaneously. Uses the same Nearby Connections infrastructure.

Privacy

• No real names exchanged — anonymous display names only
• Achievement IDs are opaque strings (no personal data)
• Opt-in via Settings → Social toggle (vibeBeaconEnabled)
• Bluetooth/Location permissions required