01Identity
One concept, many surface forms
Names, aliases, separators, casing, and punctuation fragment equivalent preference signals before ranking begins.
LEXICAL SIGNALS BEFORE RANKING
Turn noisy tags into a usable recommendation signal.
TagSpark normalizes aliases, models curated semantic neighbors, and ranks results through an explicit evidence hierarchy.
MEDIA PLACEHOLDER · PREFERENCE-TO-RANKING LOOP
- ROLE
- Language Systems & Full-stack Developer
- DURATION
- 2026
- CLIENT
- Independent Product
- RESPONSIBILITIES
- Text normalization, alias sets, category taxonomy, hand-curated similarity thesaurus, weighted ranking, product design, APIs, database, and deployment
- TOOLS
- React 18, TypeScript, Vite, Tailwind CSS, Neon Postgres, Vercel
- LINKS
- Live product GitHub
PROBLEM
A recommender is only as useful as the metadata beneath it.
User-generated tags are inconsistent by nature. Exact string matching misses aliases, near-synonyms, and category context, so subjective preference must become a canonical, comparable signal before ranking.
02Similarity
Related is not identical
Near-synonyms and neighboring concepts need partial credit without being collapsed into the same canonical tag.
03Control
Ranking needs visible rules
Users should be able to inspect and revise their inputs while the system keeps its evidence hierarchy explainable.
How might we turn noisy, subjective tags into recommendation signals that remain controllable and explainable?
01 · ALIAS NORMALIZATION
Surface variants collapse before comparison.
Each tag expands into its name and known aliases. Tokens split on commas, middle dots, slashes, and pipes, then pass through lowercase, Unicode NFKC normalization, whitespace removal, and punctuation stripping before set overlap is evaluated.
surface tags→normalized tokens→canonical alias set
Alias-collapse illustration
PLACEHOLDER · SURFACE VARIANTS → ONE CANONICAL TAG
02 · HAND-BUILT SIMILARITY THESAURUS
Meaning extends beyond string identity.
Curated clusters compile into a tag-to-tag graph. Related concepts receive partial credit even when they are not aliases, making the resource a small, interpretable thesaurus rather than a learned similarity model.
Cluster-neighbor view
PLACEHOLDER · CURATED TAG GRAPH · FIXED 0.6 EDGES
03 · HIERARCHICAL WEIGHTED SCORING
Ranking follows an explicit hierarchy of stronger and weaker evidence.
Every work tag uses the strongest matching layer, multiplied by its category weight and adjusted for core-tag bonuses. The final score is divided by the square root of tag count so tag-heavy works do not dominate by volume alone.
The same tag ID.
Normalized alias overlap inside the same category.
A hand-curated semantic neighbor.
Different tags that still share a preference dimension.
CATEGORY WEIGHTS
Worldview / setting 1.0 · relationship / genre 0.9 · mood 0.8 · fixed pairing 0.7 · length 0.5 · completion 0.4
Tag-select → live results
PLACEHOLDER · PERFECT MATCH + SIMILARITY-RANKED RESULTS
Why this result?
PLACEHOLDER · LAYER, CATEGORY WEIGHT, BONUS + NORMALIZATION
04 · SEMANTIC INCLUDE / EXCLUDE
Exclusion follows meaning, not only the clicked string.
Excluded concepts expand through alias sets and cluster neighbors, removing their variants and near-synonyms rather than only one tag ID. The same lexical resource supports both retrieval and control.
- INPUT
- Selected exclusion
- EXPANSION
- Aliases + cluster neighbors
- RESULT
- Semantically filtered works
SYSTEM DESIGN
The lexical resource can become shared, inspectable data.
Today the curated graph lives in application code. A behavior- preserving migration would store rename-safe tag pairs, per-edge weights, and provenance in Postgres, then rebuild the same lookup shape for scoring.
- CURRENT
- Hardcoded named clusters · fixed 0.6
- NEXT
- ID-based weighted edges · source provenance
- GUARDRAIL
- Regression parity before removing the fallback
Catalog + thesaurus architecture
PLACEHOLDER · REACT → VERCEL API → NEON + SCHEDULED REFRESH
TAKEAWAYS
What building TagSpark clarified about recommendation systems
Metadata quality determines recommendation quality. A normalization layer, curated similarity resource, and explicit scoring policy can already produce useful, controllable rankings before model complexity—and provide a clear baseline for what comes next.
01Move the thesaurus from code into data+
Store rename-safe tag relationships as weighted edges with provenance, preserving the current 0.6 baseline while allowing the resource to grow without a redeploy.
02Make alias matching more precise+
Prefer exact normalized-token intersection and gate substring containment behind word-boundary or minimum-length checks.
03Create one source of truth for categories+
Share a typed category definition between the ranking logic and interface so ordering and weights cannot drift.
04Pin the scoring contract with tests+
Verify that exact beats alias, alias beats broader similarity, core bonuses apply, and length normalization preserves the intended ordering.
05Return stable, meaningful result order+
Replace per-render shuffling with a stable sort or seeded shuffle so returning users can understand why ordering changed.