obsidian-exist/docs/superpowers/specs/2026-03-27-obsidian-exist-plugin-design.md

Obsidian Exist Plugin — Design Spec

Date: 2026-03-27 Status: Approved

Overview

A native Obsidian plugin (TypeScript) that syncs Exist.io personal tracking data into Obsidian daily notes. Replaces the existing Python CLI tool (exist-client) with an in-app experience that works on both desktop and mobile.

Goals

• Sync Exist.io attribute data, insights, and tags into daily notes automatically on startup
• Provide manual sync and backfill commands
• Produce identical note output to the Python exist-client tool
• Work on desktop and mobile (iOS/Android)
• Feel like a polished, native Obsidian plugin

Non-Goals

• Configurable attribute group visibility (can be added later)
• Writing data back to Exist.io
• Any UI beyond settings tab, ribbon icon, status bar, and notices
• Rate limiting or retry logic for API calls (deferred)
• Automated tests (manual testing against real API and vault)

---

Architecture

The plugin is structured as five focused modules:

obsidian-exist/
├── src/
│   ├── main.ts          — Plugin entry point, lifecycle, commands, ribbon, status bar
│   ├── api.ts           — Exist.io API client
│   ├── notes.ts         — Note rendering, section replacement, frontmatter
│   ├── settings.ts      — Settings tab UI and defaults
│   └── daily-notes.ts   — Daily Notes / Periodic Notes plugin path resolution
├── manifest.json
├── package.json
├── esbuild.config.mjs
└── tsconfig.json

Data flow: On startup (and on manual trigger), main.ts resolves the target date(s), calls api.ts to fetch Exist data, then calls notes.ts to render and write each note. File paths are resolved at sync time via daily-notes.ts.

---

Module Designs

api.ts — Exist.io API Client

• Uses Obsidian's requestUrl for all HTTP calls (required for mobile compatibility; never use fetch or Node built-ins)
• Bearer token authentication via Authorization: Bearer <token> header
• Base URL: https://exist.io/api/2
• Fetches from two endpoints:
  • attributes/with-values/ — query params: date_max (ISO date of most recent day), days (count of days in range), limit: 100
  • insights/ — query params: date_min (ISO date), date_max (ISO date), limit: 100
• Handles pagination by following the next URL in the response body (only the first request sends query params; subsequent pagination requests follow next as-is)
• Maximum 31-day range — backfill input is clamped to 31

Data types:

• AttrValue: { value: any, valueType: number, label: string, group: string, groupLabel: string }
• ExistData: { date: string, attrs: Record<string, AttrValue>, tags: string[], insights: string[] }
• The attrs map key is the attribute name field from the API response (e.g. "mood", "steps")

Tag data source: ExistData.tags is populated exclusively from boolean custom attributes — there is no separate tags endpoint. Non-custom boolean attributes do not produce tags.

Boolean-to-tag conversion — handled entirely in api.ts, not in notes.ts:

• Attribute valueType === 7 (boolean) AND group === "custom" AND value === 1 → label is added to ExistData.tags
• These attributes are never stored in attrs
• All other valueType 7 attributes (non-custom) are stored in attrs normally

Insight shape: Each insight object from the API has target_date (ISO date string) and text (string). Only the text field is stored in ExistData.insights.

---

notes.ts — Note Rendering & File I/O

Identical logic to Python notes.py.

Value formatting (by valueType):

• 0 (integer) / 8 (scale): str(int(value)) → e.g. 8432
• 1 (float): one decimal place → e.g. 6.3
• 3 (duration, in minutes): 7h 12m; if under 60 minutes: 45m
• 5 (percentage): one decimal place + % → e.g. 23.4%
• 2 (string), 4 (TimeOfDay), 6 (Period), unknown: str(value) → e.g. Berlin, 23:15

Zero-omission rules:

• Omit if valueType is 0, 3, 5, or 8 (integer, duration, percentage, scale) AND value equals 0
• Exception: mood (by attribute name) is never omitted regardless of value
• valueType 1 (float): zero is a legitimate value — never omitted
• valueType 2 (string): empty string is a legitimate value — never omitted

Attribute grouping: Rendered in this order by group name (short name from the API response group.name field, not the display label):

["mood", "sleep", "activity", "workouts", "productivity", "health",
 "food and drink", "finance", "events", "location", "media", "social",
 "weather", "twitter"]

This matches the Python exist-client source. Unknown groups fall after "twitter", sorted alphabetically.

Implementation note: On the first development run, log the raw group.name values from the API response to verify the exact strings for multi-word groups (e.g. "food and drink" vs "food_and_drink"). Update the array if they differ from the list above. The ordering comparison is a literal string match.

Group rendering: Each group gets a ### GroupLabel heading (using the groupLabel from the API). The custom group is handled specially (see below).

mood_note rendering: Within the Mood group, mood_note is deferred and rendered as a blockquote at the end of the group, after all other mood attributes, separated by a blank line: > text. If the value is blank/whitespace, it is omitted entirely.

Custom group: Non-boolean custom attributes and tags are rendered together under ### Custom. Non-boolean custom attrs appear as Dataview-style inline fields (Label:: value) — same format as all other attributes. Boolean custom attrs (converted to tags) appear as Tags:: tag1, tag2 at the end of the section.

Insights: Rendered under ### Insights as blockquotes: > insight text. One line per insight.

Section replacement:

1. Find the line ## Exist in the note content
2. Find the end of the section: next ## heading or EOF
3. Replace the range in-place, stripping trailing blank lines from the old section
4. Append a blank line separator before any content that follows (only if there is content after the section)
5. If no ## Exist section exists, append the new section to the end of the note (with a blank line separator if the note is non-empty)
6. All other note content is preserved exactly
7. The rendered section always ends with exactly one \n; no additional trailing newline is added when the section is at the end of the file

Frontmatter update strategy:

• Parse the YAML frontmatter block into a key-value map
• Update only mood (integer, from attrs["mood"].value) and exist_tags (list of tag strings)
• All other existing frontmatter keys are preserved untouched
• Re-serialize the full frontmatter block; this may reorder keys relative to hand-edited frontmatter (acceptable trade-off)
• exist_tags is always written, even if empty (written as exist_tags: [])
• mood is only written if the mood attribute is present in the data

New note creation: When the daily note does not exist:

1. Create all parent directories recursively (on mobile: call vault.adapter.mkdir for each intermediate path; vault.create does not create parent directories automatically)
2. Create the file with default frontmatter: created: <ISO date> and up: "[[Calendar]]"
3. Then apply the normal section replacement logic (appends ## Exist to empty content)

Idempotency: Re-syncing the same date produces identical output.

---

daily-notes.ts — Path Resolution

Resolves the vault-relative file path for a given date by reading configuration from whichever daily notes plugin is active.

Plugin precedence: If both are active, Periodic Notes takes precedence over Daily Notes.

Periodic Notes plugin (periodic-notes, community plugin):

• Settings accessed via: (app.plugins.plugins['periodic-notes'] as any)?.settings?.daily
• Relevant fields: folder (string, vault-relative folder), format (moment.js date format string, e.g. YYYY-MM-DD)

Daily Notes plugin (daily-notes, Obsidian core plugin):

• Settings accessed via: (app.internalPlugins.getPluginById('daily-notes') as any)?.instance?.options
• Relevant fields: folder (string), format (moment.js date format string)

Path construction: <folder>/<date formatted with format>.md — use moment.js (bundled with Obsidian) to format the date.

Fallback: If neither plugin is installed/enabled, show a Notice: "Obsidian Exist: Daily Notes or Periodic Notes plugin required. Please enable one and configure it." and abort the sync.

---

settings.ts — Settings

User-facing settings:

• existToken (string) — Exist.io personal API token; password-masked input field; link to exist.io/account/api/
• syncOnStartup (boolean, default: true) — whether to sync yesterday on Obsidian open

Internally stored (not user-facing, stored in data.json):

• lastSyncedDate (string, ISO date, default: "") — the most recently successfully synced date; drives both the status bar display and startup sync logic. For backfill, this is updated after each day completes (set to that day's date), so it reflects the most recently written note even if backfill is interrupted mid-run.

---

main.ts — Plugin Entry Point

On load:

1. Load settings from data.json
2. Register ribbon icon (calendar icon)
3. Register status bar item (desktop only; skip on mobile via Platform.isMobile)
4. Register commands
5. Update status bar from lastSyncedDate
6. If syncOnStartup is enabled and token is set: sync yesterday silently

Commands:

• "Sync Exist.io data" — syncs yesterday; available in command palette; assignable to hotkey
• "Backfill Exist.io data" — opens a modal with a number input (<input type="number" min="1" max="31">) labelled "How many days back?", plus OK and Cancel buttons. On OK: non-numeric or out-of-range values are clamped to 1–31; blank/empty input aborts with no action. On Cancel: close modal, no sync. Syncs the resulting range with progress notices.

Backfill date range: date_max is yesterday; days are processed newest-first (yesterday, then day before, etc.) so the most recent data appears quickly.

Ribbon icon: Triggers "Sync Exist.io data" (same as command).

Status bar item (desktop only):

• "Exist: YYYY-MM-DD" (the actual date from lastSyncedDate) after a successful sync
• "Exist: never" if lastSyncedDate is empty
• "Exist: error" if the last sync failed
• Clicking it triggers "Sync Exist.io data"

Notice behavior:

• Startup sync: silent on success; Notice on error only
• Manual sync: Notice on success ("Exist.io synced") and on error
• Backfill: progress Notice ("Exist.io: syncing 3/7…") updated as each day completes; final success/error Notice at end

---

Error Handling

• Missing token: Notice prompting user to open plugin settings
• Daily Notes / Periodic Notes plugin not found/configured: Notice explaining the dependency; abort sync
• API 401: Notice "Exist.io: invalid token. Check plugin settings."
• Network error: Notice "Exist.io: network error. Check your connection."
• Date with no Exist data: Skip silently (log to console), continue to next date
• All errors set status bar to "Exist: error" (desktop only)

---

Mobile Compatibility

• All HTTP: requestUrl only — never fetch, XMLHttpRequest, or Node built-ins
• File creation: vault.adapter.mkdir called recursively for parent directories before vault.create
• Status bar: registered only on desktop (Platform.isMobile guard)
• No path, fs, or other Node.js module imports
• moment (date formatting): imported from Obsidian's bundled version, not npm

---

Dependencies

• Obsidian API — all platform APIs (vault, settings, UI, moment)
• Daily Notes / Periodic Notes plugin — runtime dependency for note path resolution; not bundled
• No external npm runtime dependencies

Dev dependencies: esbuild (bundler), TypeScript, @types/node, obsidian type definitions