A technical overview of how the GRANSHAN Portal syncs data with Notion — architecture, sync jobs, caching, and troubleshooting.
Architecture Overview
The GRANSHAN Portal runs on Laravel 12 with Livewire 4 for reactive UI components. Data flows between the portal and Notion through the Notion API, with a local SQLite cache for fast reads and offline resilience.
The data flow is straightforward: the Notion Workspace sends data via API calls to the Sync Service, which writes to the SQLite Cache. The Laravel App reads from that cache and renders the UI through Livewire components.
How Sync Works
Scheduled Sync Jobs
The portal runs background sync jobs at regular intervals:
-
Full sync — Runs daily at 03:00 UTC. Pulls all records from configured Notion databases.
-
Incremental sync — Runs every 15 minutes. Fetches only records modified since the last sync.
-
On-demand sync — Triggered manually from the admin dashboard or via API endpoint.
What Gets Synced
-
Brand kit metadata — Notion → Portal, incremental frequency
-
Jury profiles — Notion → Portal, incremental frequency
-
Submission records — Notion → Portal, incremental frequency
-
Evaluation scores — Portal → Notion, real-time
-
User activity logs — Portal → Notion, batched hourly
SQLite Cache Layer
The local SQLite database serves as an intermediate cache:
-
Reduces API calls — Notion API rate limits are respected by reading from cache
-
Improves latency — Local reads are sub-millisecond vs. 200-500ms API calls
-
Enables offline reads — Portal remains functional during brief Notion outages
Troubleshooting
Sync Not Running
-
Check the Laravel scheduler is active
-
Verify the Notion integration token in your environment config is valid
-
Review sync logs for error details
Stale Data
-
Trigger an on-demand sync from Admin → Sync Status
-
If issues persist, run a full cache rebuild
Rate Limit Errors
The Notion API allows 3 requests per second. The sync service implements exponential backoff automatically. If you see persistent 429 errors:
-
Reduce concurrent sync workers
-
Increase the incremental sync interval
-
Check for other integrations consuming the same rate limit