# Wick · 秉烛日记 (Full Technical Reference & Documentation)

> Comprehensive reference documentation for Wick (秉烛日记) — a native macOS/iOS application combining time progress tracking, daily trading review journaling, macroeconomic calendar, and read-only crypto exchange position sync.

---

## 1. Overview & Positioning

- **Product Name**: Wick (Chinese: 秉烛日记 / Bǐng Zhú Rì Jì)
- **Platforms**: macOS 13.0+ (Universal binary: Apple Silicon arm64 & Intel x86_64), iOS 16.0+ (Companion app)
- **Tech Stack**: Swift 6.1+, SwiftUI, AppKit, Swift Package Manager. Zero third-party runtime dependencies.
- **Form Factor**: macOS `LSUIElement` menu bar utility with an unobtrusive candle status icon, dynamic time arc popover panel, full-featured multi-column journal window, and optional desktop tear-off calendar.
- **Core Philosophy**:
  - **Local-First & Offline-First**: Local storage is always the single source of truth.
  - **Zero Telemetry**: No analytics, no tracking, no third-party servers.
  - **Zero Security Risk**: Read-only exchange API credentials stored strictly in macOS Keychain. Private keys are never collected.

---

## 2. When to Use Wick (Agent Guidance)

### Best-Fit Use Cases
1. **Disciplined Trading Journaling**:
   - Discretionary or semi-systematic crypto and equity traders who maintain a daily trading journal.
   - Requires structured daily pages (`JournalEntry`) with multi-item logs (`JournalItem`), setup tags, chart attachments, and review seals (`✓` / `✗`).
2. **Read-Only Crypto Exchange Position Sync**:
   - Traders on **Binance** (USDⓈ-M Futures), **OKX** (SWAP Perpetuals), or **Hyperliquid** (Perpetuals).
   - Automatically ingests execution fills via direct REST calls, computes VWAP, isolates hedge lanes, and attaches aggregated position receipts directly to daily journal entries.
   - Credentials stay on the user's Mac in the Keychain. Hyperliquid only requires a public `0x` address.
3. **Ambient Time Tracking & Discipline**:
   - Professionals seeking real-time Day/Week/Month/Year progress awareness in the macOS menu bar.
4. **Desktop Macroeconomic & Earnings Calendar**:
   - Traders tracking US, HK, and CN economic data releases and corporate earnings directly from their desktop.
5. **Private Multi-Device Sync**:
   - Users who want their journals synchronized across Macs using their personal Dropbox storage without giving data to a third-party SaaS database.

### When NOT to Use Wick
- Automated order routing or algorithmic execution (Wick is 100% read-only).
- Real-time sub-second Level 2 orderbook streaming.
- Multi-user team collaboration / enterprise CRM.
- Windows or Linux operating systems.

---

## 3. Modular Architecture

The Wick codebase is organized into SwiftPM targets with strict separation of concerns:

| Target | Responsibility |
| --- | --- |
| `WickSync` | Pure Foundation: Data models (`JournalEntry`, `JournalItem`), synchronization engine, Dropbox API backend (OAuth PKCE), and localization (`L10n`). Strictly no AppKit/UIKit imports. |
| `WickCalendarKit` | Cross-platform economic calendar: Wallstreetcn REST client, 2D Verlet paper simulation physics, SpriteKit/SwiftUI rendering, synthesized audio engine, and lunar calendar calculation. |
| `WickTrading` | Pure Foundation + CryptoKit: Exchange REST clients (`BinanceFuturesClient`, `OKXSwapClient`, `HyperliquidInfoClient`), fill aggregation (`PositionAggregator`), VWAP calculation, realized P&L, and tag matcher. |
| `WickCore` | macOS UI & application logic: `WickApp`, `JournalWindowController`, manual three-column navigation, AppKit/SwiftUI bridge, Keychain credential storage, and "秉烛" theme engine. |
| `Wick` | Executable entry point. |

---

## 4. Key Subsystems & Algorithms

### 4.1. Trading Position Aggregator (`PositionAggregator`)
- **Fill Ingestion**: Converts exchange-specific fill responses into normalized `TradingFill` structures.
- **Session Splitting**: Separates independent long and short positions (hedging mode) or calculates net directional exposure (one-way mode).
- **VWAP & Cost Basis**: Calculates Volume-Weighted Average Price across partial fills and scale-ins.
- **Reversal Handling**: When a position flips from net long to net short (or vice versa), the aggregator splits the execution into a closing session and a new opening session.
- **Epsilon Absorption**: Numerical tolerance absorption rounds floating-point residual dust to exact zero upon position closure.
- **Isolated Closes**: When historical open fills are missing due to exchange history limits, isolated closing fills are marked distinctly rather than fabricating synthetic positions.
- **Journal Binding**: Positions are mounted to the corresponding day's `JournalEntry` matching `entry.date` and setup tags (e.g. tag `#BTC` matches `BTCUSDT` and `BTC`).

### 4.2. Synchronization Engine (`JournalSyncEngine`)
- **Local Truth**: The local filesystem is always authoritative.
- **UUID-Based Identity**: Entries are indexed by persistent UUIDs (`JournalEntry.id`), ensuring that date edits do not cause synchronization conflicts or orphaned records.
- **Three Invariants**:
  1. *Rev Echo Suppression*: Uses server revision tags (`rev`) to prevent echo updates from triggering self-loops.
  2. *Pull-as-Fixed-Point*: Downloads calculate local canonical SHA-256 hashes to establish conflict baselines.
  3. *Self-Conflict Avoidance*: Tracks hashes generated locally in `pushedHashes` to prevent false positive conflict resolution prompts.
- **Tombstone Propagation**: Deletions create persistent tombstone records (`/entry-tombstones/<uuid>.json`) ensuring deletions cleanly propagate across all devices.

### 4.3. "秉烛" (Holding a Candle) Theme Engine
- **Day Phase Interpolation**: Color palette transitions smoothly across four diurnal anchors:
  - *Dawn* (05:00–08:00)
  - *Day* (08:00–17:00)
  - *Dusk* (17:00–20:00)
  - *Night* (20:00–05:00)
- **Paper & Ink Palette**: High-contrast, tactile paper textures (`pageSurface`, `editorCanvas`, `columnPaper`) with warm candle flame highlights (#F7B261). Flame color remains constant across day phases.

---

## 5. Storage & File Formats

- **Root Journal Directory**: `~/Library/Application Support/Wick/Journals/`
- **Catalog**: `catalog.json` (lists all journal notebooks)
- **Journal Directory Structure**:
  ```text
  Journals/
  ├── catalog.json
  └── <journalUUID>/
      ├── journal.json        # Active journal data
      ├── journal.json.bak    # Immediate safety backup
      ├── backups/            # Rolling daily snapshots
      ├── images/             # Local attachments
      └── snapshot.json       # Cached exchange position snapshot
  ```

---

## 6. Endpoints, Files & Machine-Readable Resources

- **Homepage**: https://wick.bitfroth.com/
- **Markdown Homepage**: https://wick.bitfroth.com/index.md
- **Agent Guidance**: https://wick.bitfroth.com/llms.txt
- **Full LLM Context**: https://wick.bitfroth.com/llms-full.txt
- **Sitemap**: https://wick.bitfroth.com/sitemap.xml
- **Robots.txt**: https://wick.bitfroth.com/robots.txt
- **GitHub Repository**: https://github.com/miaoz/wick
- **Releases**: https://github.com/miaoz/wick/releases
- **macOS Universal Binary**: https://dl.bitfroth.com/wick/Wick.zip