My role

Solo project. I owned the concept and product decisions, the interface and design system, and the engineering. Built with Python (Flask + htmx + Alpine.js), a design system I authored in Figma via the Figma MCP, and Claude Code as an implementation partner.

The underlying audio-analysis engine is my own, evolved over 2+ years. This case study focuses on the product I built on top of it.

What it is

Recommendation engines are good at finding things that look or sound similar. They are much worse at explaining why two songs belong together.

I wanted something different: a way to curate my own library based on how music actually sounds and how it flows, track to track.

AudiOasis is the result: a local music-intelligence suite built on top of an audio-analysis engine I’ve evolved for more than two years. It turns that analysis into two tools:

• Music Match — find tracks with similar sonic qualities.
• Mix Maker — build playlists that flow by sonic compatibility.

The suite runs over my personal Roon library of over 32,000 tracks. It replaces a collection of Streamlit prototypes with a custom product experience built on a design system I created specifically for it.

A note on the name: AudiOasis is a tip of the hat to KEXP’s long-running Audioasis, a program showcasing Pacific Northwest music. I’m a KEXP member, and the name is intended as homage.

One constraint shaped everything that followed:

Keep 100% of the logic in Python — but own every pixel.

At a glance

• Product: Two apps, one suite behind a single toggle — Music Match (deterministic sonic retrieval) and Mix Maker (serendipitous playlist generation).
• Design: A custom design system built separately and consumed by the app as framework-neutral CSS tokens.
• Architecture: Flask + htmx + Alpine.js, no build step — server-rendered HTML with all matching and sequencing logic staying in Python.
• AI-assisted workflow: Claude Code as an implementation partner, with decision docs as the source of truth. I define the patterns and constraints; AI accelerates implementation.

From model to product

AudiOasis is the latest iteration of a question I started exploring years ago:

Can I describe what music sounds like well enough to sequence it automatically?

The answer evolved through three eras of tooling: early ChatGPT exploration (2024), two Streamlit front-ends (2025) — TrackMatch and the Micro-Set Playlist apps, and finally AudiOasis (2026).

The important throughline: the interface changed repeatedly, but the underlying model remained the source of truth.

Each version was a better way to reach the same Python core. AudiOasis is the first one that feels less like a prototype and more like a product I could hand to someone else.

Why leave Streamlit?

Streamlit was the right tool for proving the engine. It was the wrong tool for turning it into a product.

The reason became a design principle:

I wanted a real, branded interface — but I refused to move the matching logic into the front end to get one.

Streamlit intentionally blurs the boundary between interface and logic. That makes it excellent for exploration, but limiting for a crafted product: you inherit its layout, components, and interaction model.

I wanted typography I chose, components I designed, and interactions I controlled, without rewriting a proven Python engine in JavaScript.

That constraint — keeping the logic in Python while owning the experience — became the foundation for the architecture that followed.

Building the design system first

AudiOasis looks like a product because, before I wrote the app, I built the system it would be built on.

I created a separate, code-first design system using Claude Code and the Figma MCP server as a bridge between design and implementation. The goal was not to create a library of screens; it was to create a shared language of decisions that could be reused, tested, and extended.

The conventional pipeline is design → spec → handoff → build. The problem is the translation layer between design intent and working software. I wanted to remove that gap: the design decisions themselves would become the thing the product was built from.

The premise:

The design artifact is the production artifact.

Tokens are the documentation. Components are the specification. The browser is the design canvas.

This also defined how I use AI. Claude is an implementation partner, not a design decision-maker. It works from explicit conventions, a CLAUDE.md rules file, and documented decisions; it can extend the system, but the taste calls — what the system should be — remain mine.

The foundational investment was not a collection of screens. It was a reusable system of decisions that could be applied consistently, whether by me or by an AI-assisted workflow.

The design system as a production system

The system is deliberately opinionated: everything is a token, never a one-off value.

A few examples:

• Color is defined through semantic roles rather than individual values, with OKLCH ramps for perceptual consistency and APCA contrast validation for accessibility.
• Typography separates scale and weight tokens to prevent one-off styling decisions, with a consistent hierarchy that can adapt across contexts.
• Governance comes from a three-layer token model: primitive → semantic → component. Components reference semantic decisions only, and locked decisions are treated like a versioned API.

The most important part was creating a reliable loop between design and implementation:

Code is the source of truth; Figma mirrors it.

I author tokens in code, then reflect them into Figma Variables and Styles so both sides use the same system. A mapping layer keeps Figma naming and CSS naming aligned without forcing either side to compromise.

Claude works inside those boundaries:

• never invent hardcoded values
• reuse existing component patterns
• treat generated output as a starting point, not finished code

The workflow became:

1. Read the design context and variables.
2. Implement against the existing token system.
3. Compare the result visually.
4. Refine the system when a new pattern emerges.

AI accelerates repetition, but it does not replace judgment. Roughly 15% of any generation still requires manual work: interaction states, responsive behavior, animation, and the decisions that only become obvious once something is on screen.

That boundary is part of the method.

How it feeds AudiOasis

The reason this architecture matters is that the design system was built to be consumed, not admired.

The durable asset is the token layer: framework-neutral CSS custom properties that AudiOasis can use directly without a build step. The app vendors in a snapshot of the design system, pinned to a specific commit, so it stays self-contained while every color, spacing decision, type scale, and interaction state still traces back to one governed source.

The design system’s own component experiments were built in Vue; AudiOasis itself runs on Flask, htmx, and Alpine.js. That separation was intentional.

The system was never tied to a framework. It was a visual and behavioral foundation that could wrap a product built with different technology because the decisions lived at the right layer.

That is what allowed a custom Python application to feel like a coherent product rather than a prototype.

The AudiOasis architecture: own the pixels, keep the logic in Python

The entire suite is built around one rule:

Keep the intelligence in Python. Own the experience in the browser.

Every meaningful interaction is an HTTP request that Flask answers with a rendered HTML fragment:

Route → Python core → Jinja partial → updated interface

htmx turns ordinary HTML attributes into those interactions — searching, filtering, regenerating playlist slots, importing data — while keeping the matching and sequencing logic in Python by construction.

Alpine.js handles only presentational state: the app toggle, expanding panels, and lightweight interactions.

The result is a deliberately simple stack:

• Flask
• htmx
• Alpine.js
• server-rendered HTML
• no build step or Node toolchain

That simplicity matters because AudiOasis lives locally alongside my Roon server. It launches with flask run and stays easy to maintain.

I considered React and Vue, but both would have pushed more state and logic into the client. That would have created a second implementation of the part that mattered most: a Python engine I had already spent years evolving.

Music Match: refining a proven engine

Music Match was where the new product layer met an existing capability.

Its predecessor was TrackMatch, and the underlying matching engine was already proven. The goal was not new science; it was turning a useful prototype into a focused product experience.

What changed was the interaction model:

• A focused search flow: choose a seed track, disambiguate it, and explore matches.
• A live-filtering results table built entirely from the AudiOasis design system.
• A feature filter panel with 15+ audio dimensions and circle-of-fifths key matching.
• A reference-track workflow: choose a second track and let the relationship between the two define the filter envelope.

One intentional product boundary: Music Match does not create playlists.

It is a reference tool. It helps answer “what belongs near this?” while listening and sequencing belong to Mix Maker.

That separation matters because the two apps solve different problems:

• Music Match is deterministic: the same seed and filters produce the same retrieval.
• Mix Maker is exploratory: it uses controlled randomness to surface possibilities.

The interface changed dramatically, but the underlying model remained the source of truth.

Mix Maker: designing for flow, not just similarity

If Music Match was a refinement, Mix Maker was the real rebuild.

The original Micro-Set Playlist App proved the idea: small groups of songs could become the building blocks of a larger playlist. But its sequencing model was based on emotion — choosing what mood should come next.

Mix Maker replaces that with a structural model: choosing what sound should flow next.

The key shift:

The old system asked:

What feeling should come next?

Mix Maker asks:

What transition will sound right next?

Each micro-set has an entry and exit character. The sequencer chains those edges together, like musical dominoes, using a strictness cascade that relaxes when a perfect transition is unavailable.

The result is a playlist generator that is intentionally collaborative:

• The system creates possibilities.
• The listener keeps control.

Per-slot locks let you preserve a discovery while the engine rebuilds around it. Replacement options come from valid candidates, not arbitrary search results. And when the rules cannot be satisfied, Mix Maker leaves a visible gap instead of quietly breaking them.

A playlist that admits “I need your input” is more useful than one that silently cheats.

Closing the loop: the whole pipeline in the app

The final step was turning AudiOasis from two tools into something I could actually maintain.

Previously, updating the system meant a collection of manual steps: export data, run scripts, import files, restart tools, and remember the sequence.

I moved that workflow into the product itself.

• Music Match imports new track analysis directly from CSV files through an idempotent upsert process.
• Mix Maker imports Roon exports, links tracks to their analysis, and rebuilds the metadata needed for sequencing.
• Both apps share the same design-system upload interaction: choose a file, receive immediate feedback, and continue without leaving the product.

No terminal. No separate maintenance scripts. No restart.

This is the difference between a clever engine and a product I actually use.

When I add music to my Roon library, keeping AudiOasis current is now part of the same listening workflow it was built to support.

The product decisions behind the system

The engineering exists to support a handful of product decisions — the kind users rarely notice directly, but feel in the experience:

• Music Match doesn’t make playlists. It is a reference tool; sequencing belongs to Mix Maker. Combining the two would blur what each tool is for. Defining what a product will not do is as much a decision as defining what it will.
• Mix Maker gives control back to the listener. Generation is intentionally serendipitous, but people should be able to preserve what works and let the system rebuild around it. Locks turn automation into collaboration rather than a one-shot result.
• A visible gap beats silently breaking a rule. When the system cannot complete a transition without violating constraints, it shows the gap instead of quietly cheating. A playlist that admits uncertainty is more useful than one that hides it.
• Automation needs a control surface. Across both apps, the pattern is the same: let the system handle complexity while keeping the person in the loop. Suggested filters can be overridden. Seeds can be changed. Imports report exactly what happened.

The through-line is deciding what the machine should do, what the person should control, and where those two should meet.

AudiOasis started as an experiment in whether music could be modeled by how it sounds. It became a product by focusing less on what the system could automate and more on how a person should interact with it.