Skip to main content

Layer Dependency Model

BookWish follows a strict 4-layer dependency model to ensure proper architectural separation and maintainable feature development.

Layer Dependencies & Build Order​

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)

Layer Descriptions​

Layer 1: Core Loop​

The foundation of the platform - the indie commerce loop.

Key Features:

  • User authentication and profiles
  • Book catalog and search
  • Wishlist management
  • Store profiles
  • Orders and checkout
  • Home store selection

Core Entities:

  • users - User accounts (guest and registered)
  • books - Global book catalog
  • wishlists - User wishlist collections
  • wishlist_items - Books on wishlists
  • stores - Independent bookstore profiles
  • orders - Order records
  • order_items - Books in orders
  • addresses - Shipping/billing addresses

Dependencies: None (this is the foundation layer)

Layer 2: Store Operations​

Advanced store management and operations.

Key Features:

  • Inventory management (native + Square sync)
  • Point of Sale (POS)
  • Trade credit system
  • Trade-in processing with BooksRun integration
  • Store websites (Next.js at bookwish.shop)
  • Shipping integration (EasyPost)

Core Entities:

  • inventory - Store-specific book inventory
  • trade_credit_accounts - Customer credit balances per store
  • trade_credit_transactions - Credit/debit ledger
  • trade_ins - Trade-in sessions
  • trade_in_items - Books traded in

Dependencies: Layer 1 (requires users, books, stores, orders)

Layer 3: Social​

Social networking and content sharing features.

Key Features:

  • Lines (short posts about books)
  • Reviews and ratings
  • Private notes (Scribbles)
  • Following system (users + stores)
  • Social feed
  • Likes and engagement

Core Entities:

  • lines - Short posts about books
  • reviews - Book reviews with ratings
  • notes - Private book notes
  • follows - User following relationships
  • store_follows - Store following
  • likes - Engagement on lines and reviews

Dependencies: Layer 1 (requires users, books, stores)

Layer 4: Programs​

Community-building programs and activities.

Key Features:

  • Book clubs with discussions
  • Reading challenges
  • Club and challenge participation tracking
  • Program-specific social interactions

Core Entities:

  • clubs - Book club definitions
  • club_books - Books selected for clubs
  • club_members - Club membership
  • challenges - Reading challenges
  • challenge_books - Challenge book lists
  • challenge_participants - Challenge participation

Dependencies: Layer 1 (users, books, stores) + Layer 3 (lines for discussions)

Implementation Phases​

Following the layer dependency model, implementation proceeds in phases:

Phase 1: Foundation (Layer 1)​

  • Database schema + migrations
  • Auth (signup, login, guest, migration)
  • User profiles
  • Book catalog + search (Google Books integration)
  • Wishlists CRUD
  • Stores (basic profile)
  • Home store selection
  • Orders (BookWish Direct only initially)
  • Stripe integration
  • Flutter app shell (tabs, navigation)
  • Book Info Overlay
  • Wish tab + wishlist UI
  • Public wishlist sharing (Next.js)

Phase 2: Social (Layer 3)​

  • Lines CRUD
  • Reviews CRUD
  • Private Notes
  • Follows (users + stores)
  • Share tab + feed
  • Profile Overlay
  • Scribbles Overlay
  • Notifications (basic)

Phase 3: Store Operations (Layer 2)​

  • Inventory management (native)
  • Square integration
  • Store orders (pickup/ship)
  • POS flow
  • Trade credit system
  • Trade-ins + BooksRun
  • Store websites (Next.js)
  • Shipping (EasyPost)

Phase 4: Programs (Layer 4)​

  • Clubs CRUD + membership
  • Club discussion (Lines)
  • Challenges CRUD + participation
  • Challenge discussion
  • Read tab UI

Phase 5: Polish​

  • Push notifications
  • Stock alerts
  • Edelweiss import
  • Advanced search/filtering
  • Premium tier features
  • Analytics

Why This Order?​

The implementation phases intentionally implement Layer 3 (Social) before completing Layer 2 (Store Operations) because:

  1. User Value First: Social features provide immediate value to all users, not just store owners
  2. Network Effects: Building the community early creates engagement and retention
  3. Validation: Social features validate the platform concept before heavy store investment
  4. Dependency Logic: Layer 3 (Social) only depends on Layer 1 (Core), so it can be built before Layer 2
  5. Parallel Development: Layer 2 advanced features (POS, store websites) can be developed after Layer 3 is live

The key insight is that Layer 2 and Layer 3 both depend on Layer 1, but are independent of each other. Layer 4 depends on both Layer 1 and Layer 3 (for discussions), so it comes last.

Cross-Layer Interactions​

While layers should respect dependencies, some entities reference multiple layers:

Lines (Layer 3) can have optional context from:

  • store_id - Posted by a store
  • club_id - Posted in a club (Layer 4)
  • challenge_id - Posted in a challenge (Layer 4)

Reviews (Layer 3) can have optional context from:

  • club_id - Written for a club (Layer 4)
  • challenge_id - Written for a challenge (Layer 4)

These cross-layer references are acceptable because they're optional and the higher layer (Layer 4) depends on the lower layer (Layer 3).

Summary​

The 4-layer model provides:

  1. Clear dependencies: Each layer knows what it can use
  2. Predictable build order: Features are implemented in a logical sequence
  3. Maintainability: Changes to lower layers don't break higher layers
  4. Scalability: New features fit naturally into the existing structure