A Designer's Experiment in AI-Augmented development

Summary

Bookstack began as a native iOS app — a simple, lovable tool for tracking books. After years of steady downloads and enthusiastic user feedback, the natural next question was: what does version 2 look like?

The answer turned out to be a full web application rebuilt from the ground up with a modern full-stack architecture, persistent cloud database, real-time API syncing, a bespoke design system, and deployment via GitHub and Railway. What started as a casual experiment on Replit evolved into a production-ready platform that honors the soul of the original app while dramatically expanding its capabilities.

But perhaps the most significant story here isn't the product, it's how it was built. This project became an extended, real-world test of whether a product designer (that's me!) with no engineering background could independently ship a full-stack web application by leveraging AI-augmented development as a realistic engineering partner. The answer, it turns out, is yes ... with important caveats about methodology, prompting discipline, and knowing exactly when to ask the right questions.

Background

Bookstack has a long history. The original idea dates back to 2006, and the iOS app that eventually shipped was the product of years of iterative thinking, multiple design partners, and a hard-won lesson in the value of simplicity. That app was built around the SLC (Simple, Lovable, Complete) framework and found a respectable audience. Over 8,400 downloads. A 4.7-star App Store rating. A mailing list of enthusiastic readers asking for more.

But the iOS app had a fundamental ceiling. No accounts. No sync. No persistent library. It was a lovable product with real structural limitations. And the world of mobile development had grown more complex and expensive. Building a native v2.0 for iOS felt like fighting uphill.

The web, by contrast, had matured dramatically. Modern JavaScript frameworks, serverless databases, and cloud deployment platforms had lowered the barrier to building sophisticated web applications. The opportunity was clear: bring Bookstack to the web with everything the original lacked: real accounts, persistent data, richer features - all while keeping the spirit of the original fully intact.

The Challenge

The central challenge of this project was not picking a tech stack or designing screens. The hard part was doing both, simultaneously, as a non-engineer, while maintaining enough architectural discipline to build something that would actually scale.

An early prototype built with Replit (a vibe coding AI development app) made this concrete: it was fast to spin up, visually promising, and completely fragile. In-memory storage meant every server restart wiped the library. There was no authentication, no database, and no path to production. The prototype validated the concept but exposed how much real engineering work remained.

Migrating off Replit introduced a handful of other problems: managing environment variables across local and production environments, wiring up a cloud database without breaking an iterative development workflow, and learning (often the hard way) that tools like drizzle-kit push and drizzle-kit generate behave very differently in practice.

And then there was the AI collaboration challenge. This turned out to be as much about product management and communication as it was about technology. This aspect of the project reminded me of the early days of my career when I was learning HTML and CSS to hack together web pages. Incredibly fun, despite the challenges.

Using Claude Code as an engineering partner is definitely powerful, but it requires a specific kind of discipline that doesn't come naturally at first. I've had to learn this and am still learning. Broad instructions produce broad, sometimes destructive results. Claude Code might refactor a component perfectly while inadvertently discarding a working part of the code you'd spent hours debugging. The workflow that actually works is simply:

There was also the traditional challenge present in any project: how do you build a visual identity and design system for a web app that feels premium and intentional. I didn't want Claude to design the app, I just needed help building it. One helpful tool turned out to involve Figma more deeply than expected, including a direct MCP bridge between Figma's design files and the development environment.

Project Goals

• Create a bespoke design system (Elegy) in Figma to ensure visual consistency and design-to-code accuracy.
• Migrate from a Replit in-memory prototype to a production-ready full-stack web application.
• Implement persistent storage via a cloud PostgreSQL database (Neon) with a typed ORM (Drizzle).
• Set up real user authentication with Google OAuth via Better Auth.
• Build an engaging book detail experience: reading status, star ratings, read history, highlights, and personal stacks.
• Integrate Google Books API and OpenLibrary for comprehensive book search and metadata.
• Deploy via GitHub + Railway with a repeatable, stable CI/CD pipeline.
• Build as a PWA for installability and offline resilience.

Research & Exploration

Methodology

Research on this project drew from three sources: years of personal experience with the iOS version (and its user feedback), competitive analysis of the book-tracking landscape, and hands-on technical exploration during the Replit prototyping phase.

The mailing list compiled from the iOS app provided a direct line to real users with real opinions. Their feedback was consistent: they wanted to log in, save their library, and track reading history across devices. They wanted highlights and notes. They wanted to see what they'd read over time. These weren't feature requests — they were the core jobs-to-be-done that the original app had explicitly deferred.

Developing the AI-Augmented Workflow

One of the most consequential research efforts of this project wasn't about users — it was about process. Over the course of building Bookstack, a repeatable AI-assisted development methodology emerged through trial, error, and (sometimes frustrating) iteration.

The workflow that proved most effective has four distinct phases.

• First: use Claude.ai (the conversational interface) as a senior engineering advisor. Describe the problem, explore the tradeoffs, diagnose root causes, and develop a clear mental model of the change before any code is written.
• Second: distill that discussion into a precise, scoped prompt for Claude Code — the terminal-based agentic tool that actually edits files. The prompt specifies exactly what to change, what to preserve, and what constraints apply.
• Third: Claude Code executes the commands in the prompt, making file-level changes across the codebase.
• Fourth: review Claude Code's output summary carefully before accepting it, verify that existing functionality is intact, and treat any fix as an iterative enhancement rather than an invitation to refactor broadly.

This four-phase pattern (discuss, prompt, execute, verify) was the single biggest factor in the quality and stability of the codebase. Deviating from it, particularly by issuing broad or ambiguous prompts, consistently produces regressions.

A parallel discovery was the value of a well-maintained CLAUDE.md. This was new to me, but very familiar for engineering veterans. A CLAUDE.md file is a project-level context document read automatically by Claude Code at the start of every session. It contains brand tokens, schema details, architectural patterns, and explicit rules (like "use Tailwind utility classes only, no inline styles"). Investing in that document early paid compounding dividends: Claude Code's output became more consistent, more aligned with the design system, and required less iteration.

The Figma MCP bridge was another significant workflow discovery. By running a connection between Figma Desktop and the development environment, it became possible to extract precise design specs: exact hex values, padding, shadow definitions, font weights, etc. This could be pulled directly from the Figma file and feed them into Claude Code prompts. This closed the gap between design intent and implementation more completely than any manual handoff process ever could. A component that might take multiple back-and-forth review cycles to get pixel-accurate could be specified precisely in a single prompt.
‍
What makes this workflow genuinely novel is not that AI wrote the code. The best part of it (for me anyway) is that I was able to hold the engineering role with enough understanding and discipline to ship something real. The many years I've worked alongside developers, I suppose their vocabulary and helpful guidance proved valuable. (Hat tip to the guys at Rosetta Stone and Sport Ngin particularly). The skill being exercised is not programming in the traditional sense. It's architectural thinking, deliberate communication, careful review, and the judgment to know when output is correct versus not quite right. These are all design skills of the modern UX designer.

Key Product Findings

Goodreads remains the dominant player in the space, but its UX has aged poorly and its acquisition by Amazon has eroded user trust. There is genuine appetite for a privacy-respecting, beautifully designed alternative. There are others in the space worth noting as well: Literal, StoryGraph, Hardcover.

The book cover is the most emotionally resonant element of any book tracking interface. Readers want to see their books, not just read their titles. This became a core design principle.

Also, readers think in terms of stacks and lists, not categories. The original app's mental model (Reading, Want to Read, Finished) maps perfectly to how people actually think about their libraries.

A "preview before adding" flow — where users can inspect a book's details before committing it to their library — dramatically reduces friction in the search-to-save interaction.

Dynamic color extraction from book covers creates an emotionally resonant hero experience that makes the app feel dynamic and personal, rather than generic.

Design Solutions

Guiding Principles

• The book is the hero.
  Every major screen is designed around the book cover. It's not just as a thumbnail, but as the emotional centerpiece of the experience. The book detail hero, with its dynamic color gradient extracted from the cover, puts the book itself at the heart of the UI.
• Familiar interactions with elevated execution.
  Status dropdowns, star ratings, date pickers — these are well-worn UI patterns. The design challenge was to execute them with craft and precision so they feel bespoke (and highly usable), not boilerplate.
• Design system first.
  Rather than designing screens ad hoc, a formal design system (Elegy) was established in Figma before significant UI work began. An explicit color palette, typographic scale, component library, and spacing rules gave every decision a foundation to stand on.
• Prompt precision as a design discipline.
  Working with Claude Code exposed something counterintuitive: the quality of the AI's output is almost entirely a function of the specificity of the human input. Broad prompts produce broad results. Soometimes those results are correct, sometimes subtly wrong, sometimes AI slop. The practice of writing a tight, scoped, well-contextualized prompt before touching any file became as important as the design work itself. Treating AI direction as a design skill — something to be refined and practiced — was a mindset shift that helped improve the results I was seeing.
• Progressive complexity.
  The app is organized so that the simplest interaction (book search) is immediately accessible, while deeper features (read history, highlights, ratings, add-to-stack) are available but never in the way.

Key Outcomes

The project is ongoing, but the core architecture is stable and the application is running in production at app.getbookstack.com. The key outcomes to date:

• Designed and implemented the Elegy design system in Figma, with a named brand palette, component library, and documented design tokens that serve as the source of truth for every UI decision.
• Successful setup of a production deployment on Railway with GitHub-based CI/CD ... a significant infrastructure leap accomplished without a dedicated DevOps resource. Railway is such a cool app, btw.
• Implemented persistent user libraries backed by Neon PostgreSQL, with Drizzle ORM handling schema management and type safety. This is one of the foundational capabilities the original iOS app never offered.
• Built and shipped Google OAuth authentication via Better Auth. Users can log in and their library persists across sessions and devices.
• Shipped a rich book detail experience with interactive status management, star ratings, read history tracking, and reader highlight recording.
• Added custom stacks to help readers curate their personal libraries. This was an often-requested feature and gives the app a competitive advantage.
• Integrated Google Books API for book search, with a "preview before adding" flow that improves the search-to-save experience.
• Implemented dynamic hero color extraction from book covers using node-vibrant, creating a visually distinctive and emotionally resonant detail page that sets the app apart aesthetically.
• Configured VitePWA for offline resilience and installability.

Conclusion

Bookstack started as an idea in a sketchbook in 2006. It became a lovable iOS app in 2018. And now in 2026 it's becoming the full-featured web application it was always meant to be. But the story of this chapter is as much about how it was built as what was built.

For most of the history of software, there was a hard boundary between people who design products and people who build them. That boundary created whole industries: design handoff tools, developer relations, the endless negotiation between what was designed and what was technically feasible. AI-assisted development is blurring that boundary in ways that are only beginning to become clear.

A product designer with no formal engineering background (albeit lots of osmosis over the years), armed with a strong design system, a disciplined prompting methodology, and AI tools sophisticated enough to act as a real engineering collaborator — built and shipped a production full-stack web application. Not a toy. Not a demo. A real app, with a real database, real authentication, a real deployment pipeline, and a visual quality bar that the original iOS app would recognize.

The implications for how product teams work and what individual contributors can realistically accomplish are significant. The bottleneck is no longer purely technical capability. It's design thinking, systems thinking, communication precision, and the judgment to know good work from almost-good work. Those have always been the core skills of a strong product designer. They turn out to transfer remarkably well to directing an AI engineering partner.

Bookstack the web app isn't 100% done. But it's real, it's running, and it was built by a designer who learned that a designer who can build is no longer a contradiction in terms.