Technology Stack

Overview

BookWish uses modern, scalable technologies optimized for indie development and rapid iteration.

Layer	Technology	Purpose
Frontend	Flutter	Cross-platform app (iOS, Android, Web)
State Management	Riverpod	Reactive state management for Flutter
Backend	Node.js + TypeScript	REST API server
ORM	Prisma	Type-safe database access
Database	PostgreSQL	Primary data store
Cache	Redis	Session cache, feed cache, rate limiting
Payments	Stripe + RevenueCat	Payment processing and mobile subscriptions
Hosting	Railway (API), Vercel (Web), Supabase (DB)	Infrastructure

Frontend

Flutter

Version: Latest stable (3.x+)

Platforms:

• iOS (native)
• Android (native)
• Web (Progressive Web App)

Why Flutter:

• Single codebase for all platforms
• Native performance on mobile
• Rich UI component library (Material Design)
• Strong typing with Dart
• Hot reload for rapid development
• Growing ecosystem and community

Riverpod

State Management Pattern

BookWish uses Riverpod for:

• Global app state (auth, user, cart)
• API data caching
• Form state management
• Provider dependency injection

Key Providers:

• auth_provider - Authentication state
• user_provider - Current user data
• wishlist_provider - Wishlist state
• feed_provider - Social feed with pagination
• cart_provider - Shopping cart state
• follow_provider - Following/follower state
• moderation_provider - Block/mute state

Project Structure

/lib
├── main.dart
├── app.dart
│
├── /config
│   ├── constants.dart
│   ├── theme.dart
│   └── routes.dart
│
├── /api
│   ├── api_client.dart          # HTTP client (Dio)
│   ├── api_exception.dart
│   └── /models                   # API request/response models
│
├── /services
│   ├── auth_service.dart
│   ├── user_service.dart
│   ├── book_service.dart
│   └── ...
│
├── /state                        # Riverpod providers
│   ├── auth_provider.dart
│   ├── user_provider.dart
│   └── ...
│
├── /ui
│   ├── /pages
│   ├── /overlays                 # Modal bottom sheets
│   ├── /components
│   └── /widgets
│
└── /utils
    ├── formatters.dart
    ├── validators.dart
    └── extensions.dart

Backend

Node.js + TypeScript

Runtime: Node.js 18+ (LTS) Language: TypeScript 5+

Why Node.js + TypeScript:

• JavaScript ecosystem familiarity
• Type safety with TypeScript
• Fast development with npm packages
• Excellent async I/O performance
• Easy integration with external APIs
• Strong community support

Express.js

Web Framework

Lightweight HTTP framework for:

• REST API routing
• Middleware pipeline
• Request/response handling
• Error handling

Prisma ORM

Database Toolkit

Features:

• Type-safe database client
• Auto-generated TypeScript types
• Migration management
• Introspection and seeding
• Connection pooling

Schema Location: /backend/src/prisma/schema.prisma

Key Commands:

# Generate client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Open studio (DB GUI)
npx prisma studio

Project Structure

/src
├── index.ts                      # Entry point
├── app.ts                        # Express app setup
│
├── /config
│   ├── database.ts
│   ├── redis.ts
│   ├── stripe.ts
│   ├── square.ts
│   └── env.ts
│
├── /routes
│   ├── index.ts
│   ├── auth.routes.ts
│   ├── users.routes.ts
│   └── ...
│
├── /controllers
│   ├── auth.controller.ts
│   ├── users.controller.ts
│   └── ...
│
├── /services
│   ├── auth.service.ts
│   ├── user.service.ts
│   ├── book.service.ts
│   └── ...
│
├── /integrations
│   ├── stripe.ts
│   ├── square.ts
│   ├── ingram.ts
│   ├── easypost.ts
│   ├── booksrun.ts
│   └── google-books.ts
│
├── /middleware
│   ├── auth.middleware.ts
│   ├── tier.middleware.ts
│   ├── store-owner.middleware.ts
│   └── error.middleware.ts
│
├── /prisma
│   └── schema.prisma
│
├── /jobs                         # Background jobs
│   ├── square-sync.job.ts
│   ├── notification.job.ts
│   └── stock-alert.job.ts
│
└── /utils
    ├── validators.ts
    └── helpers.ts

Database

PostgreSQL

Version: 14+ Hosted on: Supabase

Why PostgreSQL:

• Robust relational model
• ACID compliance
• Rich data types (JSONB, arrays)
• Full-text search
• Excellent performance
• Wide ecosystem support

Key Features Used:

• UUID primary keys
• JSONB for flexible data (store hours, etc.)
• Text arrays for multi-value fields (authors, categories)
• GIN indexes for full-text search
• Timestamp with timezone (TIMESTAMPTZ)
• Foreign key constraints with cascading deletes

Redis

Version: 7+ Hosted on: Railway

Use Cases:

• Session storage
• Feed page caching (5-min TTL)
• Rate limiting
• Background job queues (Bull)
• Real-time features (pub/sub)

External Integrations

Payment Processing

Stripe

• Payment intents for orders
• Customer management
• Refund processing
• Webhook handling

RevenueCat

• Mobile subscription management (iOS/Android)
• Premium tier upgrades
• Subscription lifecycle handling
• Cross-platform receipt validation

Point of Sale

Square

• POS integration for bookstores
• Inventory sync (Square → BookWish)
• One-way data flow
• Webhook updates + hourly polling backup
• OAuth for merchant authorization

Book Data

Google Books API

• Book metadata lookup
• ISBN search
• Cover images
• Author and publisher data
• Categories and descriptions

Open Library API (Fallback)

• Alternative book data source
• ISBN lookup
• Cover images

Supply Chain

Ingram

• Book wholesale ordering
• BookWish Direct fulfillment
• Pricing and availability data
• Drop-shipping support

BooksRun

• Used book buyback quotes
• Trade-in flip option for stores
• Automated price comparison

Shipping

EasyPost

• Shipping rate calculation
• Label generation
• Carrier integration (USPS, UPS, FedEx)
• Tracking updates

Email & Notifications

SendGrid (Email)

• Transactional emails (order confirmations, etc.)
• Digest emails (daily order summaries)
• Marketing emails (opt-in)

Firebase Cloud Messaging (FCM)

• Push notifications (Android)
• Topic subscriptions
• Silent notifications for data sync

Apple Push Notification Service (APNs)

• Push notifications (iOS)
• Badge counts
• Rich notifications with images

Development Tools

Version Control

• Git - Source control
• GitHub - Repository hosting, PR reviews, CI/CD

Package Management

• npm - Node.js packages (backend)
• pub - Dart packages (Flutter)

Code Quality

• ESLint - JavaScript/TypeScript linting
• Prettier - Code formatting
• dart analyze - Flutter/Dart linting

Testing

• Jest - Backend unit and integration tests
• Flutter Test - Widget and unit tests
• Supertest - API endpoint testing

CI/CD

• GitHub Actions - Automated testing and deployment
• Railway CLI - Backend deployment
• Vercel CLI - Frontend deployment

Authentication & Security

JWT Tokens

Access + Refresh Pattern:

• Access token: 15 minutes (short-lived)
• Refresh token: 30 days (long-lived)
• HTTP-only cookies for web
• Secure token storage on mobile

Encryption

• bcrypt - Password hashing
• crypto - Sensitive data encryption (Square tokens, etc.)
• HTTPS/TLS - Transport security

Rate Limiting

• Redis-backed rate limiter
• Per-IP and per-user limits
• Different limits per tier (guest, free, premium)

Notifications Architecture

┌─────────────┐     events     ┌──────────────┐
│   API       │ ─────────────► │  Job Queue   │
│   Actions   │                │  (Bull/Redis)│
└─────────────┘                └──────────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
              ┌──────────┐    ┌──────────┐    ┌──────────┐
              │   Push   │    │  Email   │    │   SMS    │
              │  (FCM/   │    │(SendGrid)│    │ (Twilio) │
              │   APNs)  │    │          │    │(Optional)│
              └──────────┘    └──────────┘    └──────────┘

Trigger events:

• order.status_changed → push + email
• line.replied → push
• user.followed → push
• wishlist.book_in_stock → push + email
• club.new_book → push
• challenge.started → push + email

Summary

BookWish's tech stack is designed for:

1. Rapid development - Modern frameworks and tooling
2. Type safety - TypeScript and Dart throughout
3. Scalability - Stateless API, caching, background jobs
4. Developer experience - Hot reload, type generation, clear patterns
5. Cost efficiency - Serverless where possible, optimized hosting