Petstore Lookbook Rails

A Rails application demonstrating component-driven development with ViewComponent and Lookbook for the Petstore API. This project showcases modern Rails frontend patterns with isolated, reusable UI components documented in an interactive component library.

Developed and tested on FreeBSD 14.3-RELEASE - See FreeBSD Support Guide for platform-specific information.

Features

• 🎨 Component-Driven Development with ViewComponent
• 📚 Interactive Component Library using Lookbook
• 🔌 Petstore API Integration for real-world data
• 🧪 Comprehensive Testing with RSpec and component specs
• 🎯 Chrome DevTools Ready for component inspection
• 📝 Literate Programming with Org-mode documentation

Quick Start

# Clone the repository
git clone https://github.com/aygp-dr/petstore-lookbook-rails.git
cd petstore-lookbook-rails

# Install dependencies
bundle install
yarn install

# Setup database
gmake db-setup

# Start the application
gmake dev

# View component library at http://localhost:3000/lookbook

Architecture

This application demonstrates a clean separation between:

• API Client Layer: PetstoreClient service for external API communication
• Component Layer: ViewComponents for reusable, testable UI elements
• Preview Layer: Lookbook previews for component documentation and testing
• Controller Layer: Thin controllers orchestrating services and components

┌─────────────────────────────────────────┐
│          Lookbook Component UI          │
│     http://localhost:3000/lookbook      │
└─────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────┐
│          ViewComponents                 │
│  • PetCard      • OrderCard             │
│  • PetList      • InventoryGrid         │
│  • UserProfile  • Shared Components     │
└─────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────┐
│       PetstoreClient Service            │
│   • find_pets_by_status                 │
│   • get_inventory                       │
│   • get_order / get_user                │
└─────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────┐
│          Petstore API                   │
│    https://petstore3.swagger.io/        │
└─────────────────────────────────────────┘

Component Development

Creating a New Component

# Generate component with preview
rails generate component Pets::Card pet:object status:string

# Or use the Makefile
gmake component NAME=Pets::Card

Viewing in Lookbook

1. Start the Rails server: gmake dev
2. Navigate to http://localhost:3000/lookbook
3. Browse components and their various states
4. Use Chrome DevTools to inspect component structure

Testing Components

# Run component specs
gmake test-components

# Run all tests
gmake test

Available Make Targets

gmake help            # Show all available targets
gmake install         # Install all dependencies
gmake dev             # Start development server
gmake db-setup        # Setup database
gmake test            # Run all tests
gmake test-components # Run component tests only
gmake lint            # Run linters
gmake clean           # Clean temporary files

Project Structure

.
├── app/
│   ├── components/          # ViewComponents
│   │   ├── pets/           # Pet-related components
│   │   ├── store/          # Store-related components
│   │   └── shared/         # Shared components
│   ├── controllers/        # Rails controllers
│   └── services/           # Service objects
│       └── petstore_client.rb
├── test/
│   └── components/
│       └── previews/       # Lookbook previews
├── docs/                   # Documentation
│   └── diagrams/          # Architecture diagrams
├── .claude/               # Claude Code configuration
│   └── commands/          # Custom Claude commands
├── PROJECT.org            # Literate programming doc
├── README.org             # This file
├── Gemfile                # Ruby dependencies
└── Makefile              # Build automation

Development Workflow

1. Design Component - Plan component API and states
2. Create ViewComponent - Implement component logic
3. Write Preview - Add Lookbook preview scenarios
4. Develop in Lookbook - Iterate on component in isolation
5. Add Tests - Write component specs
6. Integrate - Use component in application
7. Document - Update component documentation

API Integration

The application integrates with the Swagger Petstore API v3 providing:

• Pet Management: Browse, search, and display pet information
• Store Operations: View inventory and order details
• User Management: Display user profiles

All API interactions are handled through the PetstoreClient service with proper error handling and response parsing.

Chrome DevTools Integration

Components are optimized for inspection with Chrome DevTools:

1. Enable Rails component boundaries in development
2. Use ViewComponent inspector for component tree
3. Inspect component props and state
4. Debug styles and JavaScript interactions

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Make your changes with progressive commits
4. Run tests: gmake test
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Resources

Documentation

• ViewComponent Documentation
• Lookbook Documentation
• Petstore API Documentation
• Rails Guides
• Claude Code Documentation

Platform-Specific

• FreeBSD Support Guide - Installation, configuration, and troubleshooting for FreeBSD
• FreeBSD Handbook - Official FreeBSD documentation

Acknowledgments

Built with Rails, ViewComponent, and Lookbook. API provided by Swagger Petstore.