Developer Guide

Welcome to the BookWish developer documentation! This guide provides everything you need to understand, contribute to, and deploy the BookWish platform.

Quick Start

New to BookWish development? Start here:

1. Prerequisites - Install required tools
2. Environment Setup - Set up your development environment
3. Environment Variables - Configure environment variables
4. Architecture Overview - Understand the system design
5. Code Style Guide - Learn our coding standards

Documentation Sections

Getting Started

Essential guides for setting up your development environment.

• Prerequisites - Required tools and dependencies
• Environment Setup - Backend, Flutter, and database setup
• Environment Variables - Configuration for all environments

Architecture

Comprehensive documentation of the BookWish system architecture.

• Architecture Overview - High-level system design and key decisions
• Layer Dependency Model - The 4-layer model that structures development
• Data Model - Complete database schema organized by layer
• Technology Stack - Frontend, backend, and infrastructure technologies
• Hosting & Infrastructure - Railway, Vercel, and Supabase configuration

Contributing

Guidelines for contributing code, documentation, and improvements.

• Contributing Guide - How to contribute to BookWish
• Code Style Guide - Coding standards and best practices
• Pull Request Process - How to submit and review PRs
• Commit Message Conventions - Writing clear commit messages
• Documentation Guidelines - Writing and updating documentation

Deployment

Everything related to deploying and releasing BookWish.

• Deployment Overview - Deployment targets and quick deploy steps
• Release Process - How to create and publish new releases
• CI/CD Pipeline - Continuous integration and deployment automation
• Environments - Development, staging, and production configurations
• Monitoring - Application monitoring, logging, and error tracking

Key Concepts

The 4-Layer Model

BookWish is structured in 4 architectural 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

Learn more in the Layer Model documentation.

Technology Stack

Layer	Technology	Purpose
Frontend	Flutter	Cross-platform app (iOS, Android, Web)
State	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
Payments	Stripe + RevenueCat	Payment processing
Hosting	Railway + Vercel	Infrastructure

See the complete Tech Stack documentation.

Deployment Targets

BookWish deploys to multiple platforms:

• iOS: App Store + TestFlight
• Android: Google Play Store
• Web: Vercel (Flutter Web)
• Backend API: Railway
• Store Websites: Vercel (Next.js)

Learn more in the Deployment section.

Coding Standards

We maintain high standards for code quality and consistency:

TypeScript/Node Backend

• No any type - Always use proper types
• No console logging - Use structured logging
• No TODOs - Complete implementations before committing
• No drive-by refactors - Stay focused on the task

Flutter/Dart App

• No print statements - Remove debug output
• No emoji in UI - Keep text professional
• Use Cupertino icons - SF-style icons only
• Composition over inheritance - Small, focused widgets

See the Code Style Guide for complete standards.

Common Tasks

Running the App Locally

# Backend
cd backend
npm install
npm run dev

# Flutter App
cd app
flutter pub get
flutter run

Running Tests

# Backend tests
cd backend
npm test

# Flutter tests
cd app
flutter test

Creating a Release

# From project root
npm run release

# Prompts for version number
# Automatically updates all version files
# Creates git tag and triggers CI/CD

See Release Process for details.

Contributing Code

1. Fork the repository
2. Create a feature branch
3. Make your changes following our Code Style
4. Write tests for your changes
5. Submit a Pull Request
6. Address review feedback

See Contributing Guide for complete workflow.

Project Structure

bookwish_monorepo/
├── app/                    # Flutter application
│   ├── lib/
│   │   ├── main.dart
│   │   ├── /api           # API client
│   │   ├── /services      # Business logic
│   │   ├── /state         # Riverpod providers
│   │   ├── /ui            # UI components
│   │   └── /utils         # Utilities
│   ├── ios/               # iOS specific
│   └── android/           # Android specific
│
├── backend/               # Node.js backend
│   ├── src/
│   │   ├── index.ts
│   │   ├── /routes        # API routes
│   │   ├── /controllers   # Request handlers
│   │   ├── /services      # Business logic
│   │   ├── /middleware    # Express middleware
│   │   ├── /integrations  # External APIs
│   │   └── /prisma        # Database schema
│   └── tests/
│
├── docs-site/             # Documentation (this site)
│
└── stores/                # Next.js store websites

Development Workflow

1. Pick an Issue

• Check the issue tracker
• Look for good first issue or help wanted labels
• Comment to claim the issue

2. Set Up Your Environment

• Follow Environment Setup
• Configure Environment Variables
• Verify setup by running tests

3. Make Changes

• Create a feature branch
• Follow Code Style Guide
• Write tests for your changes
• Ensure all tests pass

4. Submit PR

• Follow Pull Request Process
• Use Commit Conventions
• Respond to review feedback
• Get approval and merge

Getting Help

Documentation

• Browse this developer guide
• Check Architecture for system design
• Review Contributing guidelines

Issues & Questions

• Search existing GitHub issues
• Create a new issue with the question label
• Tag relevant maintainers in discussions

Code Examples

• Review existing pull requests
• Check the codebase for similar implementations
• See Architecture for design patterns

App Identity

Platform	Identifier
App Name	BookWish
Version	3.1.0 (Flutter rewrite)
iOS Bundle ID	Willow-Tree-Creative.bw-app
App Store SKU	Willow-Tree-Creative.bw-app
Apple ID	6748889200
Android App ID	com.willowtreecreative.bookwish
Company	Willow Tree Creative LLC

Resources

Documentation

• Architecture - System design and structure
• Getting Started - Setup and configuration
• Contributing - How to contribute
• Deployment - Release and deployment guides

External Resources

• Flutter Documentation
• Prisma Documentation
• Node.js Best Practices
• Conventional Commits

Next Steps

Ready to start developing?

1. Set up your environment → Getting Started
2. Understand the architecture → Architecture
3. Review coding standards → Code Style Guide
4. Find an issue to work on → Contributing Guide
5. Deploy your changes → Deployment

Welcome to the BookWish development community!