FocusShelf

A journal for the books, films, and music that move you.

Comment

Liuguang (留光)

Inspiration

Streaming services remember what I played, reading platforms remember what I bought, and movie databases remember what I rated—but none of them remembers why a work mattered to me.

My books, films, and music were fragmented across different apps. Notes lived elsewhere, recommendations repeated things I already knew, and personal memories gradually disappeared beneath activity feeds.

“Liuguang” means keeping the light. I wanted to create a quiet, personal place for preserving the books, films, and music that continue to glow after the experience ends.

During OpenAI Build Week, I used Codex as an ongoing product and engineering partner to turn that idea into a working native iPhone application.

What it does

Liuguang is a local-first cultural journal for books, films, and music.

Users can:

  • Record what they want to read, watch, or hear; what they are currently experiencing; and what they have completed.
  • Search multiple metadata sources without manually entering titles, creators, covers, release dates, regions, or genres.
  • Add ratings, tags, progress, and personal reflections.
  • Distinguish albums, singles, songs, EPs, and live recordings.
  • Import album track lists and lyrics, then open lyrics in a distraction-free performance mode.
  • Receive daily recommendations that exclude works already saved in the library.
  • Discover a daily quotation or scene connected to a selected work.
  • Review the year through a twelve-month activity rhythm and weighted keyword bubbles generated from recorded content.
  • Export, import, or completely erase the local library.
  • Continue viewing previously downloaded cover art without fetching it again.

The interface uses Apple’s Liquid Glass system to make the library feel less like a database and more like a living collection of memories.

How I built it

Liuguang is written in Swift 6 using SwiftUI and SwiftData, targeting iOS 26.

A provider-based metadata architecture converts every external result into one shared MediaSnapshot model. Searches can run across multiple sources, normalize inconsistent fields, remove duplicates, and retain fallback artwork and destination links.

The app currently connects to sources including Open Library, Apple Books, Google Books, Douban, IMDb, Rotten Tomatoes, Apple Music, Spotify, and LRCLIB.

Cover artwork is stored through an actor-based disk cache. URLs are hashed with CryptoKit, writes use file protection, and an LRU-style storage limit prevents the cache from growing indefinitely.

The recommendation engine remains local and explainable. It scores candidates using media-type affinity, creators, tags, daily seeds, and recent recommendation history. It balances books, films, and music, avoids excessive repetition, and removes anything already present in the user’s library.

Liquid Glass is implemented with native SwiftUI APIs such as glassEffect, GlassEffectContainer, interactive glass, and matched glass transitions. Core Motion lets the annual keyword bubbles respond to the physical tilt of the device.

How I used Codex

Codex was not a one-click code generator. I used it as a persistent collaborator throughout many small iterations.

It helped me:

  • Translate visual and interaction requirements into working SwiftUI components.
  • Trace metadata failures across different providers.
  • Design a normalized media model that could evolve without rewriting every screen.
  • Write regression tests for parsing, recommendation behavior, caching, and media classification.
  • Diagnose build errors and repeatedly compile and launch the app on an iPhone Air simulator.
  • Review Liquid Glass behavior, animation hierarchy, touch targets, and accessibility fallbacks.
  • Refactor features without discarding the user data model or unrelated working code.

The tight loop of requirement, implementation, build, observation, and correction made it possible to move from a broad product idea to a detailed native application.

Challenges

The largest technical challenge was inconsistent metadata. The same work may have different identifiers, titles, artwork sizes, release types, and descriptions across providers. Reliable importing required normalization, fallbacks, source-specific enrichment, and careful deduplication.

Music introduced another layer of complexity. A song, single, album, EP, and live recording can share almost identical metadata while requiring different presentation and import behavior.

The visual challenge was making Liquid Glass meaningful rather than decorative. Glass needed to respond to touch, preserve text contrast, transition naturally, and remain performant when several elements appeared together.

Personalized discovery was also difficult. Recommendations needed to feel fresh without becoming random, and they could never suggest something already recorded by the user.

What I learned

I learned that resilient integrations depend less on the number of APIs and more on normalization, graceful fallbacks, and clear ownership of data.

I also learned that Liquid Glass is not simply a blur effect. It works best when material, movement, hierarchy, and interaction describe the same behavior.

Most importantly, I learned that Codex produces its best work when given concrete acceptance criteria, access to the real codebase, and permission to build, test, and correct its assumptions.

Accomplishments I am proud of

  • Building a real native application rather than a static prototype.
  • Unifying three very different media types without flattening their differences.
  • Keeping the personal library local and user-exportable.
  • Creating a recommendation system that respects existing records and recent exposure.
  • Turning repeated product feedback into a coherent, reusable SwiftUI architecture.

What is next

Next, I plan to prepare a TestFlight release, add optional iCloud synchronization, build a companion Mac experience, expand the recommendation catalog, and explore an opt-in OpenAI reflection layer that can transform private notes into personal monthly or annual cultural narratives while keeping the underlying library under the user’s control.

Built With

Share this project:

Updates