8.0 KiB

Raw Blame History

Bugger for macOS — High-Level Design

Overview

Bugger is a lightweight macOS menu bar application that surfaces bugs assigned to you from a Feishu Bitable. It mirrors the experience of the Windows Bugger tool: a glanceable badge in the menu bar, a popover with your active bugs, native notifications when bugs are assigned or changed, and an optional floating widget.

Architecture

┌──────────────────────────────────────────────────────┐
│                     User's Mac                        │
│                                                       │
│  ┌─────────────┐    ┌──────────────┐                  │
│  │  Menu Bar    │    │   Floating    │                  │
│  │  Icon+Badge  │    │   Widget      │                  │
│  │  [🐛 3]     │    │  (optional)   │                  │
│  └──────┬──────┘    └──────┬───────┘                  │
│         │                  │                           │
│  ┌──────┴──────────────────┴───────┐                  │
│  │         BugStore                 │                  │
│  │    (ObservableObject)           │                  │
│  │    - bugs: [Bug]                │                  │
│  │    - unseenCount: Int           │                  │
│  │    - lastUpdated: Date          │                  │
│  └──────┬──────────────────────────┘                  │
│         │                                              │
│  ┌──────┴──────────┐    ┌─────────────┐               │
│  │  PollerService   │───▶│ FeishuService│              │
│  │  (Timer, 5min)  │    │             │               │
│  └─────────────────┘    └──────┬──────┘               │
│                                │                       │
│  ┌──────────────┐    ┌────────┴───────┐               │
│  │ Notification  │    │  TokenManager   │              │
│  │ Service       │    │  (Keychain)     │              │
│  └──────────────┘    └────────────────┘               │
│                                                       │
└──────────────────────────────────────────────────────┘
                          │
                          │ HTTPS (OAuth Bearer)
                          ▼
┌──────────────────────────────────────────────────────┐
│                  Feishu Cloud                          │
│  ┌──────────────┐    ┌──────────────────┐             │
│  │  OAuth       │    │  Bitable API      │             │
│  │  /authen/v1/  │    │  /bitable/v1/     │             │
│  │  oidc/       │    │  apps/{token}/    │             │
│  │  access_token│    │  tables/{id}/     │             │
│  └──────────────┘    │  records          │             │
│                       └──────────────────┘             │
└──────────────────────────────────────────────────────┘

Key Design Decisions

1. Native SwiftUI (not cross-platform)

The app targets macOS exclusively. SwiftUI + AppKit bridging gives the best integration with macOS idioms — MenuBarExtra, NSPanel floating windows, Keychain, and UserNotifications — while keeping the binary under 10 MB.

2. Poll-based sync, not push

Feishu webhooks require a public-facing HTTP endpoint. For a personal tool, polling the Bitable API every N minutes is simpler, safer, and sufficient. Default interval: 5 minutes.

3. OAuth user_access_token with refresh

Uses Feishu's OAuth 2.0 authorization code flow to get a user_access_token (valid 2h) and refresh_token (valid 30 days). Tokens are stored in the macOS Keychain. The app acts on behalf of the user — no admin approval needed.

4. No backend server

Everything runs locally. No database, no server, no cloud hosting. The app stores only:

OAuth tokens (Keychain)
Configuration (UserDefaults: table ID, polling interval, etc.)
Cached bug state (in-memory, rebuilt on launch)

The menu bar popover is the primary interaction surface. The floating widget is an optional companion — a small always-on-top window showing the count, which clicks through to open the menu bar popover.

Component Map

Component	Responsibility
`App`	`@main` entry, sets activation policy to `.accessory` (no dock icon)
`AppDelegate`	Menu bar icon registration, window management
`BugStore`	Central observable state: bug list, unseen count, loading/error
`FeishuService`	HTTP client for Feishu Open API (bitable records, OAuth)
`TokenManager`	OAuth flow orchestration, Keychain read/write, token refresh
`PollerService`	Configurable timer driving the fetch cycle
`NotificationService`	Diff engine + `UNUserNotificationCenter` push
`MenuBarView`	Menu bar icon with badge count
`BugListPopover`	Popover containing the scrollable bug list
`BugRow`	Single bug: title, priority pill, age, clickable
`FloatingWidget`	Optional `NSPanel`-based always-on-top overlay
`SettingsWindow`	Preferences: table config, poll interval, widget toggle
`KeychainHelper`	Thin wrapper around Security framework

Data Flow

1. App Launch
   ├── Load tokens from Keychain
   ├── If no token → show OAuth setup window
   ├── If token expired → refresh via refresh_token
   └── Start PollerService

2. Poll Cycle (every 5 min, configurable)
   ├── FeishuService.fetchRecords(table_id, filter=assignee=me)
   ├── Parse response → [Bug]
   ├── BugStore.diff(old, new)
   │   ├── New bugs → NotificationService.fire()
   │   ├── Status changes → NotificationService.fire()
   │   └── Assignee changes → NotificationService.fire()
   └── BugStore.bugs = new; BugStore.lastUpdated = now

3. User Interaction
   ├── Click menu bar icon → toggle popover
   ├── Click bug in popover → open in Feishu (browser / Feishu app URL)
   ├── "Mark all seen" → reset badge count
   └── Floating widget click → open menu bar popover

Feishu API Surface

API	Method	Purpose
`/authen/v1/oidc/access_token`	POST	Exchange authorization code for user_access_token
`/authen/v1/refresh_access_token`	POST	Refresh expired user_access_token
`/bitable/v1/apps/{app_token}/tables/{table_id}/records`	GET	Fetch bug records with filter

All calls use Authorization: Bearer <user_access_token> and go to https://open.feishu.cn.

Non-Functional Requirements

Memory: < 80 MB at steady state
CPU: idle < 0.1%, spike < 2% during poll
Binary: < 15 MB
Startup: < 2 seconds to menu bar icon visible
Offline: graceful degradation (show stale data, retry on next interval)
macOS: 14.0+ (Sonoma) — MenuBarExtra is stable from 13.3, but 14.0 is a reasonable floor for 2024+

8.0 KiB Raw Blame History