Notion Integration Services
Last Updated: 2026-05-27
Bidirectional sync between the local SQLite database and four Notion databases.
Architecture
Orchestrator / PersistenceService
↓
NotionSyncService (per-entity sync methods + bulk pull/push)
↓
NotionRepositoryManager → Notion*Repository → Notion API
↓
Entity mappers (KnowledgeMapper, CategoryMapper, …)
↓
NotionMarkdownContentService (page body blocks)There is no AbstractNotionSync hierarchy in the current codebase. Sync logic lives in NotionSyncService, which delegates to entity-specific repositories and mappers.
NotionSyncService
Central sync service with methods for each entity:
| Method | Direction | Entity |
|---|---|---|
syncKnowledgeToNotion() | Local → Notion | Knowledge |
syncCategoryToNotion() | Local → Notion | Category |
syncDigestToNotion() | Local → Notion | Digest |
syncSubscriptionToNotion() | Local → Notion | Subscription |
syncKnowledgeFromNotion() | Notion → Local | Knowledge (bulk) |
syncCategoriesFromNotion() | Notion → Local | Category (bulk) |
syncToNotion() | Local → Notion | Bulk push |
Called from persistence services after create/update, from NotionSyncController for manual sync, and from console commands.
Supporting Services
| Service | Role |
|---|---|
NotionRepositoryManager | Resolves local Doctrine repos vs remote Notion repos |
NotionKnowledgeRepository | Knowledge database CRUD on Notion |
NotionCategoryRepository | Categories database CRUD |
NotionDigestRepository | Digests database CRUD |
NotionSubscriptionRepository | Subscriptions database CRUD |
NotionPageBuilder | Builds Notion page property payloads |
NotionPropertyExtractor | Reads typed values from Notion properties |
NotionMarkdownContentService | Embeds Markdown body content as Notion blocks |
Notion Databases
| Database | Entity |
|---|---|
| Knowledge | Knowledge |
| Categories | Category |
| Digests | Digest |
| Subscriptions | Subscription |
Sync Flow
Constants & Mappers
Notion property names and limits live under App\Constants\Notion\. Entity ↔ Notion mapping is handled by dedicated mapper classes (KnowledgeMapper, CategoryMapper, etc.) — not ad-hoc arrays in sync code.