[LC-1468] Add Ed.link LMS integration for automatic credential issuance (POC) by AlexFicachi · Pull Request #975 · learningeconomy/LearnCard

AlexFicachi · 2026-01-30T20:19:56Z

Overview

https://www.loom.com/share/f7c1cd97e16642e78f887d45260ea1a4

🎟 Relevant Jira Issues

📚 What is the context and goal of this PR?

Adds Ed.link LMS integration that automatically issues credentials to students when they complete assignments. Schools connect their LMS (Google Classroom, Canvas, etc.) via Ed.link, and the system polls for assignment completions every 5 minutes, issuing credentials to students via email (using the inbox claim flow).

🥴 TL;DR:

Connect LMS → Teacher returns graded assignment → Credential auto-issued to student

💡 Feature Breakdown

Backend:

Polling service checks Ed.link every 5 mins for new completions
Issues credentials via issueToInbox()
Tracks issued credentials in Neo4j to prevent duplicates
New routes: create/delete connections, toggle auto-issue, view issued credentials

Frontend:

School Portal dashboard at /school-portal
View LMS connections, assignment completions, issued credentials
Toggle auto-issuance per connection
Delete connections and credential records (for testing)

Feature Flags:

Frontend: edLinkEnabled via LaunchDarkly (hot toggle)
Backend: EDLINK_ENABLED env var (requires restart)
Polling: EDLINK_POLLING_ENABLED sub-flag

🛠 Important tradeoffs made:

POC uses hardcoded system issuer - Not per-connection signing authorities. Sufficient for POC, but not prod ready.
Routes are unauthenticated - openRoute used for all Ed.link endpoints. Sufficient for POC, needs auth before prod.
Non-atomic deduplication - Race condition possible if concurrent polls.
Inefficient completion queries - Fetches all classes → all assignments → all submissions on every poll. No incremental/delta fetching, so refetches already-processed data every 5 minutes.

🔍 Types of Changes

New feature (non-breaking change which adds functionality)

💳 Does This Create Any New Technical Debt?

Yes
- Auth needed on routes before production
- Replace hardcoded issuer with per-connection signing authorities
- Prevent concurrent poll races

Testing

🔬 How Can Someone QA This?

Watch Here (Same loom video at the top of this post under "Overview")

Set EDLINK_ENABLED=true and EDLINK_POLLING_ENABLED=true in brain service
Enable edLinkEnabled flag in LaunchDarkly
Navigate to /school-portal
Connect an LMS via Ed.link onboarding flow
Toggle auto-issuance ON for the connection
Have a student complete an assignment in the LMS
Wait up to 5 minutes (or check brain service logs for poll)
Verify credential appears in student's notifications/inbox

📱 🖥 Which devices?

Chromium, tested in Docker local environment

🧪 Code Coverage

Unit tests in brain-service/test/edlink.spec.ts covering:
- Connection CRUD
- Issued credential tracking
- Deduplication logic
- Polling service functions

Documentation

📝 Documentation Checklist

User-Facing Docs

N/A for POC

Internal/AI Docs

Code comments - Polling service and helpers documented with file-level JSDoc headers
Feature doc - brain-service/docs/edlink-auto-issuance.md covers architecture, key files, feature flags, and POC limitations

💭 Documentation Notes

✅ PR Checklist

Related to a Jira issue
My code follows style guidelines
I have manually tested common end-2-end cases
I have reviewed my code
I have commented my code, particularly where ambiguous
New and existing unit tests pass locally with my changes
I have completed the Documentation Checklist above

🚀 Ready to squash-and-merge?:

Code is backwards compatible
There is not a "Do Not Merge" label on this PR
I have thoughtfully considered the security implications of this change.
This change does not expose new public facing endpoints that do not have authentication
- ⚠️ Ed.link routes use openRoute - acceptable for POC behind feature flag, needs auth before production

✨ PR Description

Purpose: Add Ed.link LMS integration with automatic credential issuance for completed assignments using polling-based synchronization and system-level credential signing.

Main changes:

Implemented Ed.link Graph API integration with Neo4j models for tracking connections and issued credentials with deduplication
Added background polling service that issues OpenBadgeCredentials to students via Universal Inbox when assignments are graded
Created School Portal UI with connection management, completion tracking, and auto-issuance toggle with instant credential preview

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}

…ck, removing auto-fetch cascade

…ingle API call

changeset-bot · 2026-01-30T20:20:00Z

⚠️ No Changeset found

Latest commit: d2b7714

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 · 2026-01-30T20:20:01Z

✅ Deploy Preview for staging-learncardapp ready!

Name	Link
🔨 Latest commit	`d2b7714`
🔍 Latest deploy log	https://app.netlify.com/projects/staging-learncardapp/deploys/69b9df3bc71b900008bef3d9
😎 Deploy Preview	https://deploy-preview-975--staging-learncardapp.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-01-30T20:20:06Z

✅ Deploy Preview for learncarddocs canceled.

Name	Link
🔨 Latest commit	`d2b7714`
🔍 Latest deploy log	https://app.netlify.com/projects/learncarddocs/deploys/69b9df3b43de3f0008f8fb2c

github-actions · 2026-01-30T20:20:13Z

👋 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	`CLAUDE.md`

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

…and UI controls

… by default

…ions and add multi-completion coverage

…nd, env var for backend)

…ker crash

gitstream-cm

✨ PR Review

The PR implements a comprehensive Ed.link integration with good test coverage. However, there are two notable bugs: phantom connection creation on backend failures and silent data truncation in pagination logic.

2 issues detected:

🐞 Bug - Creates phantom connection in UI when backend save fails, leading to inconsistent state and confusing UX. 🛠️

Details: When backend save fails, the connection is still added to local state. This creates an inconsistent state where the connection appears in the UI but doesn't exist in the database. Any operations on this connection will fail, and the connection will disappear on page refresh, creating a confusing user experience.
File: apps/learn-card-app/src/pages/schoolPortal/SchoolPortalDashboard.tsx (57-62)
_{🛠️ A suggested code correction is included in the review comments.}

🐞 Bug - Silently truncates data after 10 pages without warning, causing missing credentials for completions beyond the limit.

Details: The fetchAllPages function has a hardcoded maxPages default of 10, and silently stops fetching when this limit is reached. This can cause incomplete data fetching for classes, people, and enrollments, potentially resulting in missing credentials for students. If an LMS has more than 10 pages of any resource, those beyond page 10 will be silently ignored without any warning or logging.
File: services/learn-card-network/brain-service/src/helpers/edlink.helpers.ts

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 · 2026-02-09T22:01:24Z

apps/learn-card-app/src/pages/schoolPortal/SchoolPortalDashboard.tsx

+            // Still update local state for UX
+            setConnections(prev => {
+                if (prev.some(c => c.id === connection.id)) return prev;
+                return [...prev, connection];
+            });
+            setSelectedConnection(connection);


🐞 Bug - Phantom Connection: Remove the fallback local state update in the catch block (lines 58-62). Instead, show an error notification to the user when the backend save fails, so they know the connection was not created successfully.

Suggested change

// Still update local state for UX

setConnections(prev => {

if (prev.some(c => c.id === connection.id)) return prev;

return [...prev, connection];

});

setSelectedConnection(connection);

// TODO: Show error notification to the user

Is this review accurate? Use 👍 or 👎 to rate it

If you want to tell us more, use /gs feedback e.g. /gs feedback this review doesn't make sense, I disagree, and it keeps repeating over and over

…468-edlink

netlify · 2026-03-17T23:09:49Z

✅ Deploy Preview for app-store-1-basic-launchpad-app canceled.

Name	Link
🔨 Latest commit	`d2b7714`
🔍 Latest deploy log	https://app.netlify.com/projects/app-store-1-basic-launchpad-app/deploys/69b9df3b15b89e000811bc90

gitstream-cm · 2026-03-17T23:13:42Z

🥷 Code experts: TaylorBeeston, rhen92

TaylorBeeston, rhen92 have most 👩‍💻 activity in the files.
TaylorBeeston, rhen92 have most 🧠 knowledge in the files.

See details

.github/workflows/test.yml

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR
FEB	2 additions & 1 deletions
JAN
DEC
NOV	33 additions & 0 deletions
OCT

Knowledge based on git-blame:
TaylorBeeston: 20%

apps/learn-card-app/compose-local.yaml

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR	1 additions & 1 deletions
FEB	15 additions & 0 deletions	49 additions & 0 deletions
JAN	297 additions & 233 deletions
DEC	2 additions & 2 deletions
NOV	247 additions & 0 deletions
OCT

Knowledge based on git-blame:
TaylorBeeston: 76%
rhen92: 13%

apps/learn-card-app/src/Routes.tsx

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR	12 additions & 0 deletions
FEB		19 additions & 26 deletions
JAN
DEC
NOV	305 additions & 0 deletions
OCT

Knowledge based on git-blame:
TaylorBeeston: 73%
rhen92: 5%

packages/learn-card-types/src/index.ts

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR
FEB
JAN
DEC
NOV	13 additions & 0 deletions
OCT

Knowledge based on git-blame:
TaylorBeeston: 86%

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

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR
FEB
JAN
DEC
NOV	6 additions & 0 deletions
OCT

Knowledge based on git-blame:
rhen92: 79%
TaylorBeeston: 8%

services/learn-card-network/brain-service/src/docker-entry.ts

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR
FEB	21 additions & 9 deletions
JAN
DEC
NOV	32 additions & 0 deletions
OCT

Knowledge based on git-blame:
rhen92: 64%
TaylorBeeston: 27%

services/learn-card-network/brain-service/src/models/index.ts

Activity based on git-commit:

	TaylorBeeston	rhen92
MAR
FEB	94 additions & 197 deletions
JAN	3 additions & 0 deletions
DEC
NOV	37 additions & 0 deletions
OCT	86 additions & 7 deletions

Knowledge based on git-blame:
TaylorBeeston: 53%
rhen92: 27%

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

AlexFicachi added 5 commits January 28, 2026 19:14

Add Ed.link LMS integration with School Portal dashboard

ff01c43

Merge branch 'main' into lc-1468-edlink

901f4b4

WIP: Add backend persistence for Ed.link LMS connections

29b9b5d

Simplify ConnectionDetail to fetch only completion data on button cli…

8b0f956

…ck, removing auto-fetch cascade

Move Ed.link completion queries to backend, simplifying frontend to s…

9eb0c47

…ingle API call

AlexFicachi had a problem deploying to ci-tests January 30, 2026 20:20 — with GitHub Actions Failure

Remove dead frontend Ed.link code after backend migration (~1,700 lines)

67a30e4

AlexFicachi had a problem deploying to ci-tests January 30, 2026 20:31 — with GitHub Actions Failure

AlexFicachi added 3 commits February 4, 2026 13:59

Add Ed.link auto-credential issuance with polling service, tracking, …

326fd32

…and UI controls

Fix Ed.link polling to use correct DOMAIN_NAME env var

76a0f48

Add delete connection button to Ed.link dashboard and enable polling…

9ca7c95

… by default

AlexFicachi temporarily deployed to ci-tests February 6, 2026 05:19 — with GitHub Actions Inactive

Merge branch 'main' into lc-1468-edlink

143da62

AlexFicachi temporarily deployed to ci-tests February 6, 2026 19:31 — with GitHub Actions Inactive

Refactor polling service tests to BDD style with database-only assert…

da0ef66

…ions and add multi-completion coverage

AlexFicachi temporarily deployed to ci-tests February 6, 2026 21:44 — with GitHub Actions Inactive

Add feature flag to gate Ed.link integration (LaunchDarkly for fronte…

ddadaad

…nd, env var for backend)

AlexFicachi had a problem deploying to ci-tests February 6, 2026 22:28 — with GitHub Actions Failure

Add lightweight documentation for Ed.link auto-issuance POC

cfbb115

AlexFicachi changed the title ~~[DRAFT] Lc 1468 edlink~~ [LC-1468] Add Ed.link LMS integration for automatic credential issuance (POC) Feb 6, 2026

AlexFicachi had a problem deploying to ci-tests February 6, 2026 23:39 — with GitHub Actions Failure

Fix CI test failures and delay Ed.link polling startup to prevent Doc…

aecf8f0

…ker crash

AlexFicachi temporarily deployed to ci-tests February 7, 2026 01:56 — with GitHub Actions Inactive

AlexFicachi marked this pull request as ready for review February 7, 2026 01:59

gitstream-cm bot added the 30 min review label Feb 7, 2026

merge main

ecc3a01

AlexFicachi temporarily deployed to ci-tests February 9, 2026 21:58 — with GitHub Actions Inactive

gitstream-cm bot reviewed Feb 9, 2026

View reviewed changes

Merge branch 'main' of github.com:learningeconomy/LearnCard into lc-1…

d2b7714

…468-edlink

gerardopar temporarily deployed to ci-tests March 17, 2026 23:09 — with GitHub Actions Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[LC-1468] Add Ed.link LMS integration for automatic credential issuance (POC)#975

[LC-1468] Add Ed.link LMS integration for automatic credential issuance (POC)#975
AlexFicachi wants to merge 16 commits intomainfrom
lc-1468-edlink

AlexFicachi commented Jan 30, 2026 •

edited by gitstream-cm bot

Loading

Uh oh!

changeset-bot bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

netlify bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

netlify bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 30, 2026

Uh oh!

gitstream-cm bot left a comment

Uh oh!

gitstream-cm bot Feb 9, 2026

Uh oh!

netlify bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

gitstream-cm bot commented Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

AlexFicachi commented Jan 30, 2026 • edited by gitstream-cm bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

🎟 Relevant Jira Issues

📚 What is the context and goal of this PR?

🥴 TL;DR:

💡 Feature Breakdown

🛠 Important tradeoffs made:

🔍 Types of Changes

💳 Does This Create Any New Technical Debt?

Testing

🔬 How Can Someone QA This?

📱 🖥 Which devices?

🧪 Code Coverage

Documentation

📝 Documentation Checklist

💭 Documentation Notes

✅ PR Checklist

🚀 Ready to squash-and-merge?:

✨ PR Description

Uh oh!

changeset-bot bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

netlify bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for staging-learncardapp ready!

Uh oh!

netlify bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for learncarddocs canceled.

Uh oh!

github-actions bot commented Jan 30, 2026

🏄 Windsurf Tip

Uh oh!

gitstream-cm bot left a comment

Choose a reason for hiding this comment

✨ PR Review

Uh oh!

gitstream-cm bot Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

netlify bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for app-store-1-basic-launchpad-app canceled.

Uh oh!

gitstream-cm bot commented Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AlexFicachi commented Jan 30, 2026 •

edited by gitstream-cm bot

Loading

changeset-bot bot commented Jan 30, 2026 •

edited

Loading

netlify bot commented Jan 30, 2026 •

edited

Loading

netlify bot commented Jan 30, 2026 •

edited

Loading

netlify bot commented Mar 17, 2026 •

edited

Loading