academy.ecoworld.ai

Academy Link System

The Academy Link system provides stable, short, and controllable URLs for EcoWorld Academy courses.

Instead of linking directly to LearnWorlds URLs, the manual links to:

https://academy.ecoworld.ai/

Example:

https://academy.ecoworld.ai/x4zktada

The code redirects to the real LearnWorlds course URL stored in Cloudflare KV.

This architecture allows links to remain stable even if course URLs change.

---

Why this system exists

Direct course links can change over time.

If the manual linked directly to LearnWorlds, every document would need updating.

The Academy Link system solves this by introducing a stable redirect layer.

Benefits:

• Stable URLs in documentation
• Courses can move without breaking links
• Central management of links
• Analytics via PostHog
• Easy internal catalog of all courses
• Versioning support

---

System architecture

User
↓
academy.ecoworld.ai/
↓
Cloudflare Worker
↓
Cloudflare KV database
↓
Target LearnWorlds course

Components:

Component	Role
Cloudflare Worker	Handles redirects and catalog page
Cloudflare KV	Stores code → course mappings
GitHub repo	Stores seed JSON files
GitHub Action	Syncs JSON files to KV
LearnWorlds	Hosts courses

---

URL structure

Course link

https://academy.ecoworld.ai/

Example:

https://academy.ecoworld.ai/x4zktada

Result:

302 redirect → LearnWorlds course

---

Catalog page

Internal catalog of all course codes:

https://academy.ecoworld.ai/catalog

Features:

• HTML dashboard
• Shows code, label, status, target URL
• Protected with Basic Auth

---

Data structure

Each course link is stored as a JSON object in KV.

Example:

{
  "code": "x4zktada",
  "target_url": "https://ecoworld-academy.learnworlds.com/course/esrs-e1",
  "status": "draft",
  "label": "ESRS E1 Masterclass",
  "locale": "en",
  "version": 1,
  "allow_params": true,
  "host_allowlist": ["*.learnworlds.com"]
}

Field meanings:

Field	Meaning
code	Short link identifier
target_url	Destination URL
status	draft / live / archived
label	Human readable course name
locale	Language
version	Incremented when edited
allow_params	Pass query parameters
host_allowlist	Security host filter

---

Status behaviour

Status	Behaviour
draft	Redirects but marked unfinished
live	Normal redirect
archived	Redirect disabled

---

Creating a new course link

Step 1 — Generate a code

Codes are typically 8 characters.

Example:

x4zktada

Codes can be generated in Excel.

---

Step 2 — Create JSON file

Create:

seed/x4zktada.json

Example:

{
  "code": "x4zktada",
  "target_url": "https://ecoworld-academy.learnworlds.com/course/esrs-e1",
  "status": "draft",
  "label": "ESRS E1 Masterclass",
  "locale": "en",
  "version": 1,
  "allow_params": true,
  "host_allowlist": ["*.learnworlds.com"]
}

Note: This is auto created in the associated Excel file.

---

Step 3 — Commit to GitHub

git add seed/x4zktada.json
git commit -m "Add ESRS E1 course link"
git push

GitHub Actions will automatically sync the file to KV.

---

Manual hotfix

If a course must be updated immediately without waiting for CI:

wrangler kv key put --binding REDIRECTS --remote x4zktada --path seed/x4zktada.json

Example:

wrangler kv key put --binding REDIRECTS --remote x4zktada --path seed/x4zktada.json

---

Viewing stored links

To retrieve a stored record:

wrangler kv key get --binding REDIRECTS --remote x4zktada --text

---

Testing links

Check redirect:

curl -I https://academy.ecoworld.ai/x4zktada

Expected:

HTTP/2 302
location: https://ecoworld-academy.learnworlds.com/course/esrs-e1

---

Security

The catalog page is protected by Basic Auth.

Credentials are stored as Worker secrets.

wrangler secret put BASIC_AUTH_USER
wrangler secret put BASIC_AUTH_PASS

---

Analytics

Each redirect logs an event to PostHog.

Example event:

academy_redirect

Captured properties:

• code
• redirect status
• target URL

---

Failure behaviour

If a code does not exist:

redirect → /catalog

This prevents broken links in documentation.

---

Operational tips

Best practices:

• Keep codes short and random
• Use draft status until course is published
• Increment the version when updating links
• Never link manuals directly to LearnWorlds

---

Maintenance

Common tasks:

Task	Command
Add link	Commit new JSON
Update link	Edit JSON and push
Emergency update	Wrangler KV put
View link	Wrangler KV get
Test redirect	curl

---

Future improvements

Potential enhancements:

• Search in catalog
• Locale-aware routing
• Public API for links
• Scheduled backups of KV
• Analytics dashboards

---

Summary

The Academy Link system provides a stable redirect layer between documentation and course URLs.

It ensures links in the EcoWorld manual remain permanent and maintainable even as course infrastructure evolves.

---