# sota-mitsumori/pennykeep architecture

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

- Interactive diagram: https://gitdiagram.com/sota-mitsumori/pennykeep
- Repository: https://github.com/sota-mitsumori/pennykeep

## Overview

##### Project type and purpose
- This is primarily an iOS personal-finance tracking app (“PennyKeep”) built in Swift/SwiftUI, plus a small static “PennyKeepWebsite” for marketing.
- Purpose: let end users record incomes and expenses, categorize them, even scan receipts, all on‐device.

##### File structure
- Top‐level Xcode project (`PennyKeep.xcodeproj`) and Swift source files under `PennyKeep/`.
- `PennyKeep/Transactions/`: holds models (`Transaction.swift`), a persistence/store component (`TransactionStore.swift`), the receipt‐scanning logic (`ReceiptParsing.swift`, `ReceiptScannerView.swift`), plus views and view‐models for categories and transaction lists.
- Root SwiftUI entry points: `PennyKeepApp.swift`, `ContentView.swift`, plus feature views: `HomeView.swift`, `SettingsView.swift`, `CategoryView.swift`.
- A separate directory `PennyKeepWebsite/` with HTML/CSS for a static marketing site.
- A CI script (`ci_scripts/ci_pre_xcodebuild.sh`) hinting at a build pipeline.

##### README for additional insights
- Confirms an iOS app with a polished UI for tracking income/expenses.
- No explicit backend or cloud services—data is managed locally on the device.

a. Main components to represent:
- Mobile App (client)
- SwiftUI Views (ContentView, HomeView, Transaction Views, SettingsView)
- ViewModels / Controllers (CategoryManager, TransactionStore)
- Data Models (Transaction)
- Persistence Layer (e.g., UserDefaults/CoreData wrapper in TransactionStore)
- Device APIs (Camera + VisionKit for receipt scanning)
- Static Website (marketing)
- HTML/CSS assets served over CDN or static host
- CI Pipeline (pre-build script, code signing, test runner)
b. Relationships and interactions:
- UI → ViewModel → Model → Persistence
- ReceiptScannerView → iOS Camera API → ReceiptParsing → TransactionStore
- App Store distribution to end users
- CI pipelines triggered on Git commits, leading to Xcode build and App Store upload
- Static site served separately (no direct coupling to mobile app at runtime)
c. Architectural patterns and design principles:
- MVVM (Views bound to state in TransactionStore/CategoryManager)
- Single‐source‐of‐truth for transaction data
- Modular feature grouping (Transactions folder encapsulates feature)
- Unidirectional data flow (SwiftUI/Combine style)
d. Key technologies and frameworks:
- SwiftUI, Combine (state binding)
- Xcode project structure, Info.plist configuration
- Apple VisionKit or Vision framework for OCR/receipt parsing
- Static site: plain HTML/CSS
- CI shell script for pre-build checks

##### Detailed capture of architecture
- Don’t simply list files—group them into conceptual layers: Presentation, Business Logic, Data, Device Integration, CI/CD, Marketing.
- How each SwiftUI View ties back to its ViewModel and Model.
- Receipt-scanning path as a sub-flow.
- Version control and build pipeline as a supporting infrastructure layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        AppEntry["PennyKeepApp"]:::presentation
        Content["ContentView"]:::presentation
        Home["HomeView"]:::presentation
        Settings["SettingsView"]:::presentation
        CategoryScreen["CategoryView"]:::presentation
        AddTxView["AddTransactionView"]:::presentation
        TxListView["TransactionsView"]:::presentation
        CatMgrView["CategoryManagerView"]:::presentation
        ReceiptUI["ReceiptScannerView"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic" 
        direction TB
        CatMgr["CategoryManager"]:::logic
        TxStore["TransactionStore"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        TransactionModel["Transaction"]:::data
    end

    %% Device Integration
    subgraph "Device Integration" 
        direction TB
        OCR["ReceiptParsing"]:::device
        CameraAPI["Camera / VisionKit"]:::device
    end

    %% CI/CD Infrastructure
    subgraph "CI/CD & Build" 
        direction TB
        CIJob["ci_pre_xcodebuild.sh"]:::infra
        XcodeProj["Xcode Project Files"]:::infra
    end

    %% Marketing Website
    subgraph "Marketing Website" 
        direction TB
        HTML["index.html"]:::marketing
        CSS["styles.css"]:::marketing
        AssetsSite["assets/"]:::marketing
    end

    %% Connections
    AppEntry -->|"launches"| Content
    Content -->|"navigates to"| Home
    Home -->|"selects settings"| Settings
    Home -->|"selects categories"| CategoryScreen
    Home -->|"adds transaction"| AddTxView
    Home -->|"views transactions"| TxListView
    Home -->|"manages categories"| CatMgrView
    Home -->|"scans receipt"| ReceiptUI

    AddTxView -->|"uses"| CatMgr
    TxListView -->|"binds to"| TxStore
    CatMgrView -->|"binds to"| CatMgr
    ReceiptUI -->|"invokes"| CameraAPI
    ReceiptUI -->|"parses via"| OCR
    OCR -->|"saves to"| TxStore

    CatMgr -->|"updates"| TransactionModel
    TxStore -->|"CRUD on"| TransactionModel

    CIJob -->|"runs before build"| XcodeProj
    XcodeProj -->|"packages app"| AppEntry
    CIJob -->|"publishes to"| AppEntry

    %% Marketing Website served separately
    HTML --> CSS
    HTML --> AssetsSite

    %% Click Events
    click AppEntry "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/PennyKeepApp.swift"
    click Content "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/ContentView.swift"
    click Home "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/HomeView.swift"
    click Settings "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/SettingsView.swift"
    click CategoryScreen "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/CategoryView.swift"
    click AddTxView "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/AddTransactionView.swift"
    click TxListView "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/TransactionsView.swift"
    click CatMgrView "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/CategoryManagerView.swift"
    click ReceiptUI "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/ReceiptScannerView.swift"
    click CatMgr "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/CategoryManager.swift"
    click TxStore "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/TransactionStore.swift"
    click TransactionModel "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/Transaction.swift"
    click OCR "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep/Transactions/ReceiptParsing.swift"
    click CIJob "https://github.com/sota-mitsumori/pennykeep/blob/main/ci_scripts/ci_pre_xcodebuild.sh"
    click XcodeProj "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeep.xcodeproj/project.pbxproj"
    click HTML "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeepWebsite/index.html"
    click CSS "https://github.com/sota-mitsumori/pennykeep/blob/main/PennyKeepWebsite/css/styles.css"
    click AssetsSite "https://github.com/sota-mitsumori/pennykeep/tree/main/PennyKeepWebsite/assets/"

    %% Styles
    classDef presentation fill:#FFD580,stroke:#E69500,color:#000
    classDef logic fill:#80C0FF,stroke:#0073E6,color:#000
    classDef data fill:#B3FF80,stroke:#4CA600,color:#000
    classDef device fill:#FF80BF,stroke:#E60073,color:#000
    classDef infra fill:#D0D0D0,stroke:#808080,color:#000
    classDef marketing fill:#FFDB99,stroke:#E68A00,color:#000
```
