odyssey: Skill for Claude Code

Data Fetching Patterns for Odyssey

The Golden Rule

All Strapi GET requests go through fetchAPI() in lib/utils.ts. All mutations go through Server Actions in lib/actions.ts using raw fetch().

Writing a New Request Function

Template

// lib/requests/{content-type}.ts
import { fetchAPI } from "@/lib/utils";
import { CACHE_TAGS } from "@/lib/cache-tags";

export async function getThingsByFilter(filterValue: string): Promise<Thing[]> {
  return fetchAPI<Thing[]>("/things", {
    urlParams: {
      filters: { field: { $eq: filterValue } },
      populate: {
        // Only populate what you render
        relation: { fields: ["name", "slug"] },
      },
      sort: ["name:asc"],
    },
    next: { tags: [CACHE_TAGS.things], revalidate: 900 },
  });
}

Checklist Before Writing

1. Read the schema first: backend/src/api/{type}/content-types/{type}/schema.json
2. Check if a similar function exists: Grep for the content type in lib/requests/
3. Choose the right cache tag: Check lib/cache-tags.ts for existing tags
4. Decide on populate depth: Only populate fields you'll render. Never populate: "*"

Cache Tag System

Tag Types

Global tags — shared across all users:

CACHE_TAGS.droplets; // all droplet queries
CACHE_TAGS.playlists; // all playlist queries
CACHE_TAGS.lesson; // all lesson queries
CACHE_TAGS.tags; // all tag queries
CACHE_TAGS.announcements; // feed queries
CACHE_TAGS.users; // user listing queries
CACHE_TAGS.allEnrollments; // admin enrollment views

Per-user tags — scoped to individual users:

CACHE_TAGS.enrollments(userId); // "enrollments-{userId}"
CACHE_TAGS.friendships(userId); // "friendships-{userId}"
CACHE_TAGS.notes(userId); // "notes-{userId}"
CACHE_TAGS.highlights(userId); // "highlights-{userId}"

Adding a New Cache Tag

1. Add the constant to lib/cache-tags.ts
2. Use it in the request function's next.tags
3. Add revalidateTag() call in every Server Action that mutates this data
4. If per-user scoped, use the function form: CACHE_TAGS.myTag(userId)