# Apple Notes Reference Architecture

> Reference architecture for Apple Notes automation systems. Trigger: "apple notes architecture".

- Skill: `jeremylongshore/apple-notes-reference-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jeremylongshore/apple-notes-reference-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeremylongshore/apple-notes-reference-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: jeremylongshore (https://skillmd.com/u/jeremylongshore)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/jeremylongshore/apple-notes-reference-architecture

---


# Apple Notes Reference Architecture

## Architecture
```
┌────────────────────────────────────────────────┐
│                macOS Machine                     │
│                                                  │
│  ┌──────────┐   ┌───────────┐   ┌────────────┐ │
│  │ Your App │──▶│ osascript  │──▶│ Notes.app  │ │
│  │ (Node.js)│   │ (JXA/AS)  │   │ (iCloud)   │ │
│  └──────────┘   └───────────┘   └────────────┘ │
│       │                               │          │
│  ┌────▼─────┐                  ┌──────▼───────┐ │
│  │ SQLite   │                  │ iCloud Sync  │ │
│  │ Cache    │                  │ (automatic)  │ │
│  └──────────┘                  └──────────────┘ │
└────────────────────────────────────────────────┘
```

## Project Structure
```
apple-notes-automation/
├── src/
│   ├── notes-client.ts       # JXA wrapper class
│   ├── templates/             # Note templates
│   ├── export/                # Export to MD/JSON/SQLite
│   ├── events/                # Change detection polling
│   └── server.ts              # Optional: local API server
├── scripts/
│   ├── notes-cli.sh           # CLI wrapper
│   ├── export-all.sh          # Full export script
│   └── template-create.js     # JXA template engine
├── tests/
│   ├── mocks/                 # Mock client for CI
│   └── unit/                  # Unit tests
└── package.json
```

## Key Constraints
| Constraint | Impact | Workaround |
|-----------|--------|------------|
| macOS only | No Linux/Windows | Run on Mac; export for cross-platform |
| No REST API | Cannot access remotely | Local-only; export to portable format |
| iCloud sync lag | Writes may not appear instantly | Poll with delay |
| No webhooks | Cannot push events | Poll for changes |
| HTML-only body | No native Markdown | Convert on export |

## Resources

- [Mac Automation Scripting Guide](https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/)
- [JXA Examples](https://jxa-examples.akjems.com/)