# steventanyang/lefocus architecture

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

- Interactive diagram: https://gitdiagram.com/steventanyang/lefocus
- Repository: https://github.com/steventanyang/lefocus

## Overview

##### Project type and purpose
- This is a cross-platform desktop application built with Tauri.
- Frontend: React + TypeScript, served by Vite.
- Backend: Rust via Tauri, orchestrating audio playback, system “sensing,” activity segmentation, timer logic (“Island”), labels, and persisting data in a local SQLite database.
- macOS-only plugin (Swift + C FFI) to access system-level sensing APIs.

##### File structure
- Top-level:
- src/… (React Vite app)
- src-tauri/… (Rust backend + tauri.conf.json + macOS plugin under src-tauri/plugins/macos-sensing)
- scripts/… (DB migration helpers)
- package.json, bun.lock (JS/TS dependencies)
- system-design/, docs/ (design documentation)
- src-tauri modules:
- audio/ — generators (rain, binaural, brown_noise)
- db/ — connection, migrations, models, repositories (apps, sessions, segments, labels, context_readings)
- sensing/ — controller, icon_manager, loop_worker, perceptual hashing
- segmentation/ — algorithm, scoring, merge, config
- timer/ — commands, controller, state
- labels/ — CLI commands for label CRUD
- utils/ — logging, common helpers
- macos_bridge.rs — glue to Swift plugin
- Swift plugin (src-tauri/plugins/macos-sensing): exposes MacOSSensingFFI to Rust, manages audio island UI, media monitoring, artwork, interaction, window management.

##### README
- Describes setup: Rust/Cargo, Swift/Xcode CLI, Bun or npm.
- Scripts for database versioning and migrations.
- Tauri dev commands for building/testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React/TypeScript UI)" 
        direction TB
        FE1["src/"]:::frontend
        FE2["src/main.tsx"]:::frontend
        FE3["src/App.tsx"]:::frontend
        FE4["src/components/…"]:::frontend
        FE5["src/hooks/…"]:::frontend
        FE6["src/providers/QueryProvider.tsx"]:::frontend
        FE7["vite.config.ts"]:::frontend
        FE8["public/"]:::frontend
        FE9["index.html"]:::frontend
    end

    %% IPC Layer
    subgraph "Tauri IPC Layer & Entry Points"
        direction TB
        IPC1["src-tauri/src/main.rs"]:::ipc
        IPC2["src-tauri/src/lib.rs"]:::ipc
        IPC3["src-tauri/tauri.conf.json"]:::ipc
    end

    %% Rust Core Modules
    subgraph "Rust Core Modules"
        direction TB
        subgraph "Audio Module" 
            AM["src-tauri/src/audio/"]:::rust
        end
        subgraph "Database Module"
            DB["SQLite Database"]:::db
            DB1["src-tauri/src/db/connection.rs"]:::db
            DB2["src-tauri/src/db/migrations.rs"]:::db
            DB3["src-tauri/src/db/models/…"]:::db
            DB4["src-tauri/src/db/repositories/…"]:::db
            DB5["scripts/new_migration.sh"]:::db
            DB6["scripts/db_user_version.sh"]:::db
        end
        subgraph "Sensing Module"
            SM["src-tauri/src/sensing/"]:::rust
            SB["src-tauri/src/macos_bridge.rs"]:::rust
        end
        subgraph "Segmentation Module"
            SEG["src-tauri/src/segmentation/"]:::rust
        end
        subgraph "Timer Module"
            TM["src-tauri/src/timer/"]:::rust
        end
        subgraph "Labels Module"
            LM["src-tauri/src/labels/"]:::rust
        end
        subgraph "Utility Module"
            UM["src-tauri/src/utils/"]:::rust
        end
    end

    %% macOS Plugin
    subgraph "macOS Plugin (Swift + C FFI)"
        direction TB
        PL["src-tauri/plugins/macos-sensing/"]:::plugin
    end

    %% Build Helpers
    subgraph "Build & Config"
        BR["src-tauri/build.rs"]:::rust
        CT["src-tauri/Cargo.toml"]:::rust
    end

    %% Connections
    FE1 -->|uses| IPC1
    FE2 -->|uses| IPC1
    FE3 -->|uses| IPC1
    IPC1 -->|"dispatch IPC"| AM
    IPC1 -->|"dispatch IPC"| DB
    IPC1 -->|"dispatch IPC"| SM
    IPC1 -->|"dispatch IPC"| SEG
    IPC1 -->|"dispatch IPC"| TM
    IPC1 -->|"dispatch IPC"| LM
    AM -->|"playSound"| OS_AUDIO["OS Audio Subsystem"]
    SM -->|"FFI Calls"| PL
    SM -->|reads/writes| DB
    SEG -->|reads/writes| DB
    TM -->|reads/writes| DB
    LM -->|reads/writes| DB
    UM -->|logging & helpers| AM
    UM -->|logging & helpers| SM
    UM -->|logging & helpers| SEG
    UM -->|logging & helpers| TM
    UM -->|logging & helpers| LM
    DB -->|"file"| SQLite["SQLite File"]:::db
    IPC1 -->|emits events| FE1
    BR -->|build script| CT

    %% Click Events
    click FE1 "https://github.com/steventanyang/lefocus/tree/main/src/"
    click FE2 "https://github.com/steventanyang/lefocus/blob/main/src/main.tsx"
    click FE3 "https://github.com/steventanyang/lefocus/blob/main/src/App.tsx"
    click FE4 "https://github.com/steventanyang/lefocus/tree/main/src/components/"
    click FE5 "https://github.com/steventanyang/lefocus/tree/main/src/hooks/"
    click FE6 "https://github.com/steventanyang/lefocus/blob/main/src/providers/QueryProvider.tsx"
    click FE7 "https://github.com/steventanyang/lefocus/blob/main/vite.config.ts"
    click FE8 "https://github.com/steventanyang/lefocus/tree/main/public/"
    click FE9 "https://github.com/steventanyang/lefocus/blob/main/index.html"
    click IPC1 "https://github.com/steventanyang/lefocus/blob/main/src-tauri/src/main.rs"
    click IPC2 "https://github.com/steventanyang/lefocus/blob/main/src-tauri/src/lib.rs"
    click IPC3 "https://github.com/steventanyang/lefocus/blob/main/src-tauri/tauri.conf.json"
    click AM "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/audio/"
    click DB1 "https://github.com/steventanyang/lefocus/blob/main/src-tauri/src/db/connection.rs"
    click DB2 "https://github.com/steventanyang/lefocus/blob/main/src-tauri/src/db/migrations.rs"
    click DB3 "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/db/models/"
    click DB4 "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/db/repositories/"
    click DB5 "https://github.com/steventanyang/lefocus/blob/main/scripts/new_migration.sh"
    click DB6 "https://github.com/steventanyang/lefocus/blob/main/scripts/db_user_version.sh"
    click SM "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/sensing/"
    click SB "https://github.com/steventanyang/lefocus/blob/main/src-tauri/src/macos_bridge.rs"
    click SEG "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/segmentation/"
    click TM "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/timer/"
    click LM "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/labels/"
    click UM "https://github.com/steventanyang/lefocus/tree/main/src-tauri/src/utils/"
    click PL "https://github.com/steventanyang/lefocus/tree/main/src-tauri/plugins/macos-sensing/"
    click BR "https://github.com/steventanyang/lefocus/blob/main/src-tauri/build.rs"
    click CT "https://github.com/steventanyang/lefocus/blob/main/src-tauri/Cargo.toml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef ipc fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef rust fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#fff3cd,stroke:#856404,color:#856404
    classDef plugin fill:#e2d5f3,stroke:#6f42c1,color:#6f42c1
```
