Show "works with" app logos and filter by app

Integration logos

Goal: every item shows the apps it works with, found automatically, fixable by its owner, with real logos where the license allows and a clean fallback where it does not.

Steps

1. Write the catalog first. One entry per app, in code or a JSON file, never in the database. See examples/catalog.json. Each entry has:

   • id: lowercase kebab, permanent. Never rename or reuse one. Retire it instead.
   • name and group (chat, docs, payments, and so on). Groups drive the browse page.
   • Strong signals: domains, envPrefixes (like STRIPE_), mcp server names, workflowNodes (node type names in workflow JSON).
   • aliases: other spellings and product names.
   • rule: name (match the name, any case), case (the name only with its capitals, for names that are also words in lowercase), or aliases (never the bare name, for common words like Make, Linear, Box, or Square).
   • icon: the simple-icons slug, when one exists.

2. Detect from strong signals, then mentions. Run node scripts/detect-integrations.mjs --catalog examples/catalog.json --item examples/item.json to see the reference logic, then port it to your stack.

   • Strong signals first: declared integrations, MCP servers, network hosts (exact or subdomain), env var names by prefix, workflow node types.
   • Mentions second: one in the name or description, or at least two across files. Strip links first. Skip lock files and binaries.
   • Cap it: about 6 tags from mentions and 12 in all. Strong signals fill first.
   • Store ids only, never the text that matched. Record which signal found each id only if you need it for debugging, and keep that out of logs.
3. Store tags on the item. An array of ids with an index that supports "contains". Add a flag or nullable column for the owner's list. Run detection when a new version is published, inside the same publish step, so tags never lag.
4. Let the owner override. One endpoint: set a list of ids (validated against the catalog, deduped, capped), or send null to go back to automatic. While an owner list exists, new versions do not change the tags. Write an audit event for every change, with ids only.

5. Build the logo pipeline. A script that writes one SVG per catalog id:

   • Hand-supplied file in a logos folder wins. Check it with node scripts/check-svg.mjs <folder> and fail the build if it fails.
   • Otherwise take the path from the simple-icons npm package and fill it with the brand hex. Pin an exact version. Its icon data is CC0, but the marks are still trademarks: read each brand's guidelines, and note that some brands asked to be removed.
   • Brand colors too light to read on the chip get drawn in near-black.
   • Otherwise no file. Write the list of missing ids into the logos folder README so someone can supply them.
   • Generate a small list of ids that have a logo, so the UI never requests a file that is not there.

6. Show it. Same chip everywhere: a neutral light background in both themes, the mark in brand color.

   • Cards: a row of small logos, capped with "+N".
   • Detail page: named chips that link to the filtered search.
   • Browse page: every app by group with item counts, apps with zero items hidden or dimmed.
   • Search: an app filter, a heading like "Items for Slack", and a query that names an app also matches items tagged with it.
   • Missing logo: a lettered chip. Use one letter, or two (like "Sl" and "Sa") when the first letter is shared by other apps in the catalog.
   • Logos are decorative next to a visible name; otherwise give them alt text with the app name.
7. Retag what already exists. A job that recomputes tags for every item from its latest version, skips owner-set items, and has --dry-run. Print counts only: checked, changed, skipped, failed. Run the dry run first and check the counts match the database you meant to reach.

8. Test it. Use fixtures, not live data:

   • Each strong signal alone tags the app.
   • Common-word names tag only through aliases; case-rule names ignore lowercase.
   • Links and lock files never count; one file mention is not enough, two are.
   • Caps hold.
   • The owner list survives a new version, and null returns to automatic.
   • The filter returns tagged items only and combines with the text query.
   • The SVG check rejects scripts, handlers, and outside links.

Rules

• Ids are a public contract. Changing one breaks saved links and filters.
• Never store or log the file content or the text that matched. Ids and counts only.
• Add a new dependency (like simple-icons) only with the owner's yes, and pin it.
• Logos are served from your own origin, so never ship an SVG that fails the check.
• Do not guess a brand color or redraw a mark by hand. Use the official one or the lettered chip.
• Tune with real items: after the first retag, read a sample of tags and fix the catalog, not the item.