fix: Neo4j Connection Failures

[Custard7]

Problem

Sentry is logging intermittent errors:

Failed to connect to server. Please ensure that your database is listening on the correct host and port and that you have compatible encryption settings both on Neo4j server and driver. Note that the default encryption setting has changed in Neo4j 4...

The Neogma instance was initialized with no explicit driver configuration, leaving encryption and timeout behavior up to the Neo4j JS driver's defaults — which changed in v4+ to not encrypt by default. This causes a mismatch when the NEO4J_URI uses an encrypted scheme (neo4j+s://, bolt+s://), and also provides no resilience for Lambda cold-start networking delays.

Changes

services/learn-card-network/brain-service/src/instance.ts

• Auto-detect encryption from URI scheme (neo4j+s:// / bolt+s:// → TLS on, otherwise off)
• Set trust strategy to match encryption mode
• Add connection timeout (30s) and connection acquisition timeout (30s) to handle VPC/NAT cold-start latency
• Cap max connection lifetime at 8 minutes (under Lambda's 10-min ceiling)
• Limit connection pool size to 10

Root Cause

The brain service Lambda runs inside a VPC. External Neo4j connections route through a NAT Gateway, adding latency — especially during cold starts. Without explicit driver config, the Neo4j driver's default encryption setting could conflict with the URI scheme, and default timeouts were insufficient for the VPC networking path.

✨ PR Description

Purpose: Fix Neo4j connection failures by adding proper encryption detection and connection pool configuration to prevent timeouts and improve database reliability.

Main changes:

• Added automatic encryption detection from URI scheme (neo4j+s/bolt+s) with appropriate trust and encryption settings
• Configured connection pool parameters including 8-minute max lifetime, 30-second timeouts, and 10 connection pool size
• Enhanced Neogma driver initialization with production-ready connection management settings for improved stability

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Description using Guidelines Learn how}

---

Rovo Dev code review: Rovo Dev has reviewed this pull request
Any suggestions or improvements have been posted as pull request comments.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 551c0e6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for staging-learncardapp canceled.

Name	Link
🔨 Latest commit	551c0e6
🔍 Latest deploy log	https://app.netlify.com/projects/staging-learncardapp/deploys/69a7623cdf2f5700083b6217

[netlify]

✅ Deploy Preview for learncarddocs canceled.

Name	Link
🔨 Latest commit	551c0e6
🔍 Latest deploy log	https://app.netlify.com/projects/learncarddocs/deploys/69a7623c575d0d000807d594

[github-actions]

👋 Hey there! It looks like you modified code, but didn't update the documentation in /docs.

If this PR introduces new features, changes APIs, or modifies behavior that users or developers need to know about, please consider updating the docs.

---

🏄 Windsurf Tip

You can ask Windsurf to help:

"Analyze the changes in this PR and update the gitbook docs in /docs accordingly."

Windsurf will review your changes and suggest appropriate documentation updates based on what was modified.

---

📚 Documentation Guide

Change Type	Doc Location
New feature/API	docs/tutorials/ or docs/how-to-guides/
SDK/API changes	docs/sdks/
New concepts	docs/core-concepts/
App UI/UX flows	docs/apps/ (LearnCard App, ScoutPass)
Internal patterns	AGENTS.md

This is an automated reminder. If no docs are needed, feel free to ignore this message.

[gitstream-cm]

This PR is missing a Jira ticket reference in the title or description.
Please add a Jira ticket reference to the title or description of this PR.

[gitstream-cm]

✨ PR Review

LGTM

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Review using Guidelines Learn how}

[Computer8004]

🤖 Computer's Review

LGTM! This fix properly handles Neo4j connection encryption based on the URI scheme and adds sensible connection pool settings.

What I like:

• Auto-detection of encryption from URI ( or )
• Proper trust configuration for both encrypted and non-encrypted connections
• Connection timeouts prevent hanging connections
• Pool size limit prevents resource exhaustion

The changes are minimal and focused on the specific issue. Approved! ✅

[Computer8004]

🤖 Computer's Review

LGTM! This fix properly handles Neo4j connection encryption based on the URI scheme and adds sensible connection pool settings.

What I like:

• Auto-detection of encryption from URI (neo4j+s or bolt+s)
• Proper trust configuration for both encrypted and non-encrypted connections
• Connection timeouts prevent hanging connections
• Pool size limit prevents resource exhaustion

The changes are minimal and focused on the specific issue. Approved! ✅

[gitstream-cm]

✨ PR Review

The PR effectively addresses Neo4j connectivity issues by adding explicit driver configuration for encryption and timeouts. The timeout values are well-suited for Lambda cold-start scenarios.

1 issues detected:

🐞 Bug - Self-signed certificate URIs (neo4j+ssc://, bolt+ssc://) would fail certificate validation because they're incorrectly configured with TRUST_SYSTEM_CA_SIGNED_CERTIFICATES instead of TRUST_ALL_CERTIFICATES. 🛠️

Details: The encryption detection logic matches both neo4j+s:// and neo4j+ssc:// URIs (since +ssc starts with +s), but applies the wrong trust strategy to self-signed certificate URIs. When using neo4j+ssc:// or bolt+ssc:// schemes, the driver will attempt to verify against system CAs instead of accepting self-signed certificates, causing certificate validation failures.
File: services/learn-card-network/brain-service/src/instance.ts (14-20)
_{🛠️ A suggested code correction is included in the review comments.}

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Review using Guidelines Learn how}

[gitstream-cm]

🥷 Code experts: TaylorBeeston

TaylorBeeston has most 👩‍💻 activity in the files.
TaylorBeeston has most 🧠 knowledge in the files.

See details

services/learn-card-network/brain-service/src/instance.ts

Activity based on git-commit:

	TaylorBeeston
MAR
FEB
JAN
DEC
NOV
OCT

Knowledge based on git-blame:
TaylorBeeston: 100%

✨ Comment /gs review for LinearB AI review. Learn how to automate it here.