# irochi1184/kakebo architecture

> Architecture diagram of the GitHub repository irochi1184/kakebo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/irochi1184/kakebo
- Repository: https://github.com/irochi1184/kakebo

## Overview

##### Project Type and Purpose
- Project Type: Native iOS application with an accompanying WidgetKit extension.
- Architectural Style: MVVM + Combine (ObservableObject) for UI data flow, AppGroup-backed JSON persistence, local notifications, and WidgetKit integration.
- Primary Function: Fast expense/income logging, calendar visualization, recurring To-Dos, local notifications, and home-screen widget.

##### File Structure
- Top-Level Targets:
- KaKeBo (main iOS app)
- KaKeBoWidget (WidgetKit / Live Activity extension)
- Shared (code shared via AppGroup)
- Key Folders in KaKeBo:
- App (AppDelegate, main SwiftUI App entrypoint)
- Models (DTOs, domain models)
- Services (DataStore, TodoStore, ReminderStore, ThemeStore)
- Views (SwiftUI view hierarchy organized by feature: Calendar, Components, Settings, Paywall, etc.)
- Persistence & Configuration:
- JSON files under AppGroup container: transactions.json, categories.json, budgets.json
- Info.plist, entitlements (AppGroup and widget extension)
- Combine, UserNotifications, WidgetKit frameworks

##### README for Insights
- MVVM + ObservableObject pattern
- JSON-based local persistence (no CoreData)
- AppGroup container for shared data between app and widget
- WidgetKit and UserNotifications integration
- Future directions: iCloud sync, PDF reports, AI analytics

##### Main Components
a. Frontend Layer (iOS App)
- SwiftUI Views (KaKeBo/Views)
- ViewModels (ObservableObject classes in Services and Stores)
- App entrypoints: KaKeBoApp.swift and AppDelegate.swift
b. Business Logic Layer
- Models (domain structs: Transaction, Category, Budget, ToDo templates, ReminderRule, etc.)
- Services / Stores
- DataStore (handles JSON I/O, backup)
- TodoStore (manages calendar To-Dos)
- ReminderStore / ReminderManager (schedules notifications)
- ThemeStore, PurchaseManager
c. Persistence Layer
- AppGroup Directory (shared container)
- JSON files: categories.json, transactions.json, budgets.json
- Shared code: TransactionDTO and AppGroup helper in Shared/
d. System Frameworks & External Services
- Combine (data binding)
- UserNotifications (local scheduling & presentation)
- WidgetKit (home screen widget, live activity)
- AppStorage / UserDefaults (user settings)
e. Widget Extension
- KaKeBoWidgetBundle, Intent definitions, Widget entrypoint
- Reads JSON from AppGroup
- Live Activity & Timeline reload via WidgetCenter
f. Utilities & Helpers
- CSV export (ActivityView, CSVDocument)
- Keyboard observer, Haptic feedback
- Sample backup generator

##### Relationships and Data Flow
- UI Views ↔ ViewModels (@Published properties via Combine)
- ViewModels → Services/Stores (method calls for CRUD)
- Services/Stores ↔ Persistence (read/write JSON in AppGroup)
- Services → WidgetKit (WidgetCenter.shared.reloadAllTimelines())
- Services → UserNotifications (schedule/remove notifications)
- Widget Extension → Persistence (reads JSON, updates timeline)
- Triggers:
- On JSON file update → Widget reload
- On user action → DataStore.write() → JSON write

##### Architectural Patterns and Design Principles
- MVVM: separate Views, ViewModels (in Stores/Services), Models
- Reactive data flow using Combine (ObservableObject & @Published)
- AppGroup for IPC between app and widget
- Single source of truth in JSON files
- Modularization: Shared code module for DTOs and AppGroup paths
- Lightweight persistence: JSONEncoder/Decoder instead of CoreData
- Local notifications decoupled via ReminderManager

##### Detail Without Overthinking
- Every logical component folder as a separate module if it plays a distinct role
- Do not merge UI and business logic—keep Views, ViewModels, Services distinct
- AppGroup boundary clearly (show container path, shared JSON files)
- How WidgetKit and UserNotifications integrate but remain decoupled from core UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main App Layer
    subgraph "Main App" 
        direction TB
        KaKeBoApp["KaKeBoApp"]:::ui
        AppDelegate["AppDelegate"]:::ui
        subgraph "UI Views" 
            direction TB
            AddTransactionView["AddTransactionView"]:::ui
            EditTransactionView["EditTransactionView"]:::ui
            HomeView["HomeView"]:::ui
            RootTabView["RootTabView"]:::ui
            ReportsView["ReportsView"]:::ui
            CategoryListView["CategoryListView"]:::ui
            SymbolPickerView["SymbolPickerView"]:::ui
            RecurringTodoSettingsView["RecurringTodoSettingsView"]:::ui
            subgraph "Calendar Views"
                direction TB
                CalendarScreen["CalendarScreen"]:::ui
                CalendarMonthGrid["CalendarMonthGrid"]:::ui
                DayDetailSheet["DayDetailSheet"]:::ui
            end
            Components["Components Folder"]:::ui
        end
        subgraph "Business Logic - Stores/Services"
            direction TB
            DataStore["DataStore"]:::service
            DataStoreBackup["DataStore+Backup"]:::service
            TodoStore["TodoStore"]:::service
            ReminderStore["ReminderStore"]:::service
            ThemeStore["ThemeStore"]:::service
        end
        %% UI to Services
        AddTransactionView -->|"uses"| DataStore
        EditTransactionView -->|"uses"| DataStore
        HomeView -->|"binds to"| TodoStore
        HomeView -->|"binds to"| DataStore
        RootTabView -->|"binds to"| ThemeStore
        ReportsView -->|"requests export"| DataStoreBackup
        CategoryListView -->|"uses"| DataStore
        SymbolPickerView -->|"uses"| DataStore
        RecurringTodoSettingsView -->|"uses"| TodoStore
        CalendarScreen -->|"binds to"| TodoStore
        CalendarMonthGrid -->|"binds to"| TodoStore
        DayDetailSheet -->|"binds to"| TodoStore
        Components -->|"shared UI comps"| AddTransactionView
    end

    %% Shared & Persistence Layer
    subgraph "Shared & Persistence" 
        direction TB
        AppGroupHelper["AppGroup (Shared/AppGroup)"]:::model
        TransactionDTO["TransactionDTO"]:::model
        subgraph "AppGroup JSON Files"
            direction TB
            TransactionsJSON["transactions.json"]:::persistence
            CategoriesJSON["categories.json"]:::persistence
            BudgetsJSON["budgets.json"]:::persistence
        end
        %% Services to Persistence
        DataStore -->|"read/write JSON"| AppGroupHelper
        DataStore -->|"read/write"| TransactionsJSON
        DataStore -->|"read/write"| CategoriesJSON
        DataStore -->|"read/write"| BudgetsJSON
        TodoStore -->|"persist To-Dos"| AppGroupHelper
        ReminderStore -->|"store rules"| AppGroupHelper
    end

    %% Widget Extension Layer
    subgraph "Widget Extension (KaKeBoWidget)" 
        direction TB
        KaKeBoWidgetBundle["KaKeBoWidgetBundle"]:::widget
        KaKeBoWidget["KaKeBoWidget"]:::widget
        AppIntent["AppIntent"]:::widget
        WidgetControl["KaKeBoWidgetControl"]:::widget
        LiveActivity["KaKeBoWidgetLiveActivity"]:::widget
        %% Widget reads shared data
        KaKeBoWidget -->|"reads JSON"| AppGroupHelper
        LiveActivity -->|"reads JSON"| AppGroupHelper
        WidgetControl -->|"handles intents"| AppIntent
    end

    %% External Frameworks
    subgraph "System Frameworks & Services"
        direction TB
        Combine["Combine"]:::external
        UserNotifications["UserNotifications"]:::external
        WidgetKit["WidgetKit"]:::external
        UserDefaults["UserDefaults / AppStorage"]:::external
    end

    %% Service to Framework arrows
    TodoStore -->|"publishes via"| Combine
    DataStore -->|"uses"| Combine
    ThemeStore -->|"uses"| UserDefaults
    ReminderStore -->|"schedules"| UserNotifications
    KaKeBoWidget -->|"powered by"| WidgetKit
    LiveActivity -->|"powered by"| WidgetKit

    %% Click Events
    click KaKeBoApp "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/App/KaKeBoApp.swift"
    click AppDelegate "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/App/AppDelegate.swift"
    click AddTransactionView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/AddTransactionView.swift"
    click EditTransactionView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/EditTransactionView.swift"
    click HomeView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/HomeView.swift"
    click RootTabView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/RootTabView.swift"
    click ReportsView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/ReportsView.swift"
    click CategoryListView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/CategoryListView.swift"
    click SymbolPickerView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/SymbolPickerView.swift"
    click RecurringTodoSettingsView "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/RecurringTodoSettingsView.swift"
    click CalendarScreen "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/Calendar/CalendarScreen.swift"
    click CalendarMonthGrid "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/Calendar/CalendarMonthGrid.swift"
    click DayDetailSheet "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Views/Calendar/DayDetailSheet.swift"
    click Components "https://github.com/irochi1184/kakebo/tree/main/KaKeBo/Views/Components"
    click DataStore "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Services/DataStore.swift"
    click DataStoreBackup "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Services/DataStore+Backup.swift"
    click TodoStore "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Services/TodoStore.swift"
    click ReminderStore "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Services/ReminderStore.swift"
    click ThemeStore "https://github.com/irochi1184/kakebo/blob/main/KaKeBo/Services/ThemeStore.swift"
    click AppGroupHelper "https://github.com/irochi1184/kakebo/blob/main/Shared/AppGroup.swift"
    click TransactionDTO "https://github.com/irochi1184/kakebo/blob/main/Shared/TransactionDTO.swift"
    click KaKeBoWidgetBundle "https://github.com/irochi1184/kakebo/blob/main/KaKeBoWidget/KaKeBoWidgetBundle.swift"
    click KaKeBoWidget "https://github.com/irochi1184/kakebo/blob/main/KaKeBoWidget/KaKeBoWidget.swift"
    click AppIntent "https://github.com/irochi1184/kakebo/blob/main/KaKeBoWidget/AppIntent.swift"
    click WidgetControl "https://github.com/irochi1184/kakebo/blob/main/KaKeBoWidget/KaKeBoWidgetControl.swift"
    click LiveActivity "https://github.com/irochi1184/kakebo/blob/main/KaKeBoWidget/KaKeBoWidgetLiveActivity.swift"

    %% Styles
    classDef ui fill:#D0E4FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#D8F3DC,stroke:#2E7D32,color:#2E7D32;
    classDef model fill:#FFF3CD,stroke:#FFB300,color:#FFB300;
    classDef persistence fill:#FFE5B4,stroke:#F57C00,color:#F57C00;
    classDef external fill:#E0E0E0,stroke:#6E6E6E,color:#6E6E6E;
    classDef widget fill:#F0F4C3,stroke:#AFB42B,color:#AFB42B;
```
