Architecture
This section provides comprehensive architectural documentation for the BookWish platform, covering system design, dependency models, data structures, and infrastructure.
Quick Links
Core Architecture
- Architecture Overview - High-level system architecture, key design decisions, and API structure
- Layer Dependency Model - The 4-layer model that structures feature development
- Data Model - Complete database schema organized by architectural layer
Technology & Infrastructure
- Technology Stack - Frontend, backend, database, and external integrations
- Hosting & Infrastructure - Railway, Vercel, Supabase configuration and deployment
Architecture Principles
BookWish follows these core architectural principles:
1. Layer Dependency Model
The platform is structured in 4 layers with clear dependencies:
Layer 4: Programs (Challenges, Book Clubs)
↓ depends on
Layer 3: Social (Profiles, Lines, Reviews, Feed)
↓ depends on
Layer 2: Store Operations (POS, Inventory, Websites)
↓ depends on
Layer 1: Core Loop (Users, Books, Wishlists, Stores, Orders)
This model ensures:
- Clear separation of concerns
- Predictable build order
- Maintainable codebase
- Scalable feature development
See the Layer Model page for detailed information.
2. Fan-Out-On-Read Feed Architecture
The Share tab feed uses a fan-out-on-read pattern with Redis caching:
- No pre-computed timelines (simpler, suitable for current scale)
- Query composition at read time with filters
- 5-minute Redis cache for feed pages
- Seeded with curated and relevant content
3. Guest-First Experience
Guest sessions enable users to explore the platform before signing up:
- Device-based guest sessions
- Temporary wishlists and cart
- Seamless migration to registered accounts
- All guest data preserved during signup
4. Indie-First Commerce
The platform prioritizes independent bookstores:
- Home store selection and preferences
- Indie Pool revenue sharing for BookWish Direct
- Store-specific inventory and pricing
- Local fulfillment options (pickup and shipping)
Technology Overview
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Flutter | Cross-platform app (iOS, Android, Web) |
| State Management | Riverpod | Reactive state management |
| Backend | Node.js + TypeScript | REST API server |
| ORM | Prisma | Type-safe database access |
| Database | PostgreSQL (Supabase) | Primary data store |
| Cache | Redis (Railway) | Session cache, feed cache, rate limiting |
| Payments | Stripe + RevenueCat | Payment processing and subscriptions |
| Hosting | Railway + Vercel | API and web hosting |
See the Tech Stack page for comprehensive details.
Infrastructure Overview
| Component | Host | Service Type |
|---|---|---|
| Backend API | Railway | Node.js server |
| Flutter Web | Vercel | Static + SSR |
| Store Websites | Vercel | Next.js SSR |
| Database | Supabase | PostgreSQL |
| Redis Cache | Railway | Redis |
| Object Storage | Supabase Storage | S3-compatible |
See the Hosting page for deployment configuration.
Feature Gating
BookWish uses tier-based feature access:
| Feature | Guest | Free | Premium | Bookstore |
|---|---|---|---|---|
| Browse/search | ✓ | ✓ | ✓ | ✓ |
| Temp wishlist | ✓ | - | - | - |
| 1-2 wishlists | - | ✓ | ✓ | ✓ |
| Unlimited lists | - | - | ✓ | ✓ |
| Private lists | - | - | ✓ | ✓ |
| Create clubs | - | - | ✓ | ✓ |
| POS/inventory | - | - | - | ✓ |
| Store website | - | - | - | ✓ |
API Structure
Base URL: https://api.bookwish.io/v1
Key endpoint groups:
/auth- Authentication and guest migration/users- User profiles and management/books- Book catalog and search/wishlists- Wishlist management/stores- Store profiles and inventory/orders- Order management/lines- Social posts about books/reviews- Book reviews/clubs- Book clubs/challenges- Reading challenges
External Integrations
BookWish integrates with several external services:
Commerce:
- Stripe - Payment processing
- RevenueCat - Mobile subscriptions
- Square - POS integration for stores
Books:
- Google Books API - Book metadata
- Ingram - Wholesale ordering
- BooksRun - Used book buyback
Logistics:
- EasyPost - Shipping and tracking
Communication:
- SendGrid - Transactional emails
- Firebase Cloud Messaging - Push notifications (Android)
- Apple Push Notification Service - Push notifications (iOS)
Getting Started
For developers new to the BookWish codebase:
- Understand the layer model - Read the Layer Model to understand how features are organized
- Review the data model - Study the Data Model to understand entity relationships
- Set up your environment - Follow the Getting Started guide
- Explore the tech stack - Familiarize yourself with the Tech Stack
- Review coding standards - Follow the Contributing Guidelines
Next Steps
- Architecture Overview - Detailed system architecture
- Layer Model - Layer dependency rules and implementation phases
- Data Model - Complete database schema
- Tech Stack - Technology choices and project structure
- Hosting - Infrastructure and deployment