# arturn31/bookstore architecture

> Architecture diagram of the GitHub repository arturn31/bookstore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arturn31/bookstore
- Repository: https://github.com/arturn31/bookstore

## Overview

Books4You is a full-stack bookstore prototype. Readers browse and search a catalog, inspect book details and reviews, save books or manage their profiles, then use a cart and Stripe checkout to place orders and view order status. The architecture is server-first: route/UI interactions reach domain actions and services, which use repositories and Supabase; Stripe handles payment and webhook processing. The graph preserves documented discovery, account, social, and commerce capabilities. Some route and feature implementations were not sampled, so their connections rely on README statements rather than inspected calls.

Main entry points: [`utils/db/server.ts`](https://github.com/arturn31/bookstore/blob/master/utils/db/server.ts) (Supabase and PostgreSQL), [`data/checkout/services/CheckoutService.ts`](https://github.com/arturn31/bookstore/blob/master/data/checkout/services/CheckoutService.ts) (Checkout orchestration), [`data/books/BookRepository.ts`](https://github.com/arturn31/bookstore/blob/master/data/books/BookRepository.ts) (Book repository), [`data/checkout/repositories/CheckoutOrderRepository.ts`](https://github.com/arturn31/bookstore/blob/master/data/checkout/repositories/CheckoutOrderRepository.ts) (Order repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Catalog discovery"]
  node_catalog["Catalog routes and UI<br/>[page.tsx]"]
  node_catalog_manager["Catalog browsing<br/>[BooksManager.tsx]"]
  node_book_service["Book service<br/>[BookService.ts]"]
  node_search["Book search<br/>[useBookSearch.ts]"]
  node_book_details["Book details<br/>[page.tsx]"]
end

subgraph group_identity["Accounts and community"]
  node_book_reviews["Book reviews<br/>[ReviewForm.tsx]"]
  node_review_service["Review service<br/>[ReviewService.ts]"]
  node_user_reviews["User review management<br/>[useUserReviews.ts]"]
  node_auth["Authentication"]
  node_profile["Profiles and onboarding"]
  node_privacy["Privacy settings"]
  node_wishlist["Wishlist and sharing"]
end

subgraph group_commerce["Commerce and orders"]
  node_cart_ui["Cart experience<br/>[CartSidebar.tsx]"]
  node_cart_service["Cart service<br/>[CartService.ts]"]
  node_checkout_ui["Checkout form<br/>[useCheckoutForm.ts]"]
  node_checkout_action["Checkout action<br/>[CheckoutAction.ts]"]
  node_checkout_service["Checkout orchestration<br/>[CheckoutService.ts]"]
  node_stripe["Stripe payments"]
  node_orders["Order views<br/>[page.tsx]"]
  node_payment_hooks["Payment webhook and reconciliation<br/>[route.ts]"]
end

subgraph group_platform["Services and persistence"]
  node_supabase[("Supabase and PostgreSQL<br/>[server.ts]")]
  node_book_repository["Book repository<br/>[BookRepository.ts]"]
  node_order_repository["Order repository"]
  node_schema_types["Database types<br/>[database.types.ts]"]
end

node_reader(("Reader"))

node_reader -->|"browses"| node_catalog
node_catalog -->|"renders"| node_catalog_manager
node_catalog_manager -->|"fetches books"| node_book_service
node_book_service -->|"queries"| node_book_repository
node_book_repository -.->|"reads catalog"| node_supabase
node_reader -->|"searches"| node_search
node_search -->|"requests matches"| node_book_service
node_reader -->|"opens book"| node_book_details
node_book_details -->|"views reviews"| node_book_reviews
node_book_reviews -->|"submits reviews"| node_review_service
node_reader -->|"signs in"| node_auth
node_reader -->|"manages profile"| node_profile
node_reader -->|"sets visibility"| node_privacy
node_privacy -.->|"persists settings"| node_supabase
node_reader -->|"saves and shares"| node_wishlist
node_reader -->|"manages reviews"| node_user_reviews
node_user_reviews -->|"loads and deletes"| node_review_service
node_review_service -->|"reads and writes"| node_supabase
node_reader -->|"adds books"| node_cart_ui
node_cart_ui -.->|"updates cart"| node_cart_service
node_cart_service -.->|"persists cart"| node_supabase
node_reader -->|"checks out"| node_checkout_ui
node_checkout_ui -->|"submits checkout"| node_checkout_action
node_checkout_action -.->|"executes checkout"| node_checkout_service
node_checkout_service -->|"creates intent"| node_stripe
node_checkout_service -->|"persists order"| node_order_repository
node_order_repository -.->|"stores order"| node_supabase
node_reader -->|"views order"| node_orders
node_payment_hooks -->|"processes events"| node_stripe
node_payment_hooks -.->|"updates payment state"| node_supabase
node_book_repository -->|"uses database types"| node_schema_types
node_order_repository -->|"uses database types"| node_schema_types

click node_catalog "https://github.com/arturn31/bookstore/blob/master/app/page.tsx"
click node_catalog_manager "https://github.com/arturn31/bookstore/blob/master/components/books/BooksManager.tsx"
click node_book_service "https://github.com/arturn31/bookstore/blob/master/data/books/BookService.ts"
click node_search "https://github.com/arturn31/bookstore/blob/master/hooks/SearchBar/useBookSearch.ts"
click node_book_details "https://github.com/arturn31/bookstore/blob/master/app/book/%5Bslug%5D/page.tsx"
click node_book_reviews "https://github.com/arturn31/bookstore/blob/master/app/book/%5Bslug%5D/components/Reviews/ReviewForm/ReviewForm.tsx"
click node_review_service "https://github.com/arturn31/bookstore/blob/master/data/books/reviews/ReviewService.ts"
click node_user_reviews "https://github.com/arturn31/bookstore/blob/master/data/books/reviews/useUserReviews.ts"
click node_auth "https://github.com/arturn31/bookstore/tree/master/data/auth"
click node_profile "https://github.com/arturn31/bookstore/tree/master/data/user"
click node_privacy "https://github.com/arturn31/bookstore/blob/master/data/user/profile/PrivacySettingsService.ts"
click node_wishlist "https://github.com/arturn31/bookstore/tree/master/data/user/wishlist"
click node_cart_ui "https://github.com/arturn31/bookstore/blob/master/components/CartSidebar/CartSidebar.tsx"
click node_cart_service "https://github.com/arturn31/bookstore/blob/master/data/cart/CartService.ts"
click node_checkout_ui "https://github.com/arturn31/bookstore/blob/master/app/checkout/useCheckoutForm.ts"
click node_checkout_action "https://github.com/arturn31/bookstore/blob/master/data/checkout/CheckoutAction.ts"
click node_checkout_service "https://github.com/arturn31/bookstore/blob/master/data/checkout/services/CheckoutService.ts"
click node_stripe "https://github.com/arturn31/bookstore/blob/master/data/checkout/CheckoutStripeServer.ts"
click node_orders "https://github.com/arturn31/bookstore/blob/master/app/checkout/success/page.tsx"
click node_payment_hooks "https://github.com/arturn31/bookstore/blob/master/app/api/webhooks/stripe/route.ts"
click node_supabase "https://github.com/arturn31/bookstore/blob/master/utils/db/server.ts"
click node_book_repository "https://github.com/arturn31/bookstore/blob/master/data/books/BookRepository.ts"
click node_order_repository "https://github.com/arturn31/bookstore/blob/master/data/checkout/repositories/CheckoutOrderRepository.ts"
click node_schema_types "https://github.com/arturn31/bookstore/blob/master/database.types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog,node_catalog_manager,node_book_service,node_search,node_book_details toneBlue
class node_book_reviews,node_review_service,node_user_reviews,node_auth,node_profile,node_privacy,node_wishlist toneAmber
class node_cart_ui,node_cart_service,node_checkout_ui,node_checkout_action,node_checkout_service,node_stripe,node_orders,node_payment_hooks toneMint
class node_supabase,node_book_repository,node_order_repository,node_schema_types toneRose
class node_reader toneIndigo
```

## Components

### Catalog discovery

- [Catalog routes and UI](https://github.com/arturn31/bookstore/blob/master/app/page.tsx): `app/page.tsx`
- [Catalog browsing](https://github.com/arturn31/bookstore/blob/master/components/books/BooksManager.tsx): `components/books/BooksManager.tsx`
- [Book service](https://github.com/arturn31/bookstore/blob/master/data/books/BookService.ts): `data/books/BookService.ts`
- [Book search](https://github.com/arturn31/bookstore/blob/master/hooks/SearchBar/useBookSearch.ts): `hooks/SearchBar/useBookSearch.ts`
- [Book details](https://github.com/arturn31/bookstore/blob/master/app/book/%5Bslug%5D/page.tsx): `app/book/[slug]/page.tsx`

### Accounts and community

- [Book reviews](https://github.com/arturn31/bookstore/blob/master/app/book/%5Bslug%5D/components/Reviews/ReviewForm/ReviewForm.tsx): `app/book/[slug]/components/Reviews/ReviewForm/ReviewForm.tsx`
- [Review service](https://github.com/arturn31/bookstore/blob/master/data/books/reviews/ReviewService.ts): `data/books/reviews/ReviewService.ts`
- [User review management](https://github.com/arturn31/bookstore/blob/master/data/books/reviews/useUserReviews.ts): `data/books/reviews/useUserReviews.ts`
- [Authentication](https://github.com/arturn31/bookstore/tree/master/data/auth): `data/auth`
- [Profiles and onboarding](https://github.com/arturn31/bookstore/tree/master/data/user): `data/user`
- [Privacy settings](https://github.com/arturn31/bookstore/blob/master/data/user/profile/PrivacySettingsService.ts): `data/user/profile/PrivacySettingsService.ts`
- [Wishlist and sharing](https://github.com/arturn31/bookstore/tree/master/data/user/wishlist): `data/user/wishlist`

### Commerce and orders

- [Cart experience](https://github.com/arturn31/bookstore/blob/master/components/CartSidebar/CartSidebar.tsx): `components/CartSidebar/CartSidebar.tsx`
- [Cart service](https://github.com/arturn31/bookstore/blob/master/data/cart/CartService.ts): `data/cart/CartService.ts`
- [Checkout form](https://github.com/arturn31/bookstore/blob/master/app/checkout/useCheckoutForm.ts): `app/checkout/useCheckoutForm.ts`
- [Checkout action](https://github.com/arturn31/bookstore/blob/master/data/checkout/CheckoutAction.ts): `data/checkout/CheckoutAction.ts`
- [Checkout orchestration](https://github.com/arturn31/bookstore/blob/master/data/checkout/services/CheckoutService.ts): `data/checkout/services/CheckoutService.ts`
- [Stripe payments](https://github.com/arturn31/bookstore/blob/master/data/checkout/CheckoutStripeServer.ts): `data/checkout/CheckoutStripeServer.ts`
- [Order views](https://github.com/arturn31/bookstore/blob/master/app/checkout/success/page.tsx): `app/checkout/success/page.tsx`
- [Payment webhook and reconciliation](https://github.com/arturn31/bookstore/blob/master/app/api/webhooks/stripe/route.ts): `app/api/webhooks/stripe/route.ts`

### Services and persistence

- [Supabase and PostgreSQL](https://github.com/arturn31/bookstore/blob/master/utils/db/server.ts): `utils/db/server.ts`
- [Book repository](https://github.com/arturn31/bookstore/blob/master/data/books/BookRepository.ts): `data/books/BookRepository.ts`
- [Order repository](https://github.com/arturn31/bookstore/blob/master/data/checkout/repositories/CheckoutOrderRepository.ts): `data/checkout/repositories/CheckoutOrderRepository.ts`
- [Database types](https://github.com/arturn31/bookstore/blob/master/database.types.ts): `database.types.ts`

### Other components

- **Reader**

## Connections

- Reader → Catalog routes and UI: browses
- Catalog routes and UI → Catalog browsing: renders
- Catalog browsing → Book service: fetches books (evidence: `components/books/BooksManager.tsx`)
- Book service → Book repository: queries (evidence: `data/books/BookService.ts`)
- Book repository → Supabase and PostgreSQL: reads catalog
- Reader → Book search: searches
- Book search → Book service: requests matches (evidence: `hooks/SearchBar/useBookSearch.ts`)
- Reader → Book details: opens book
- Book details → Book reviews: views reviews
- Book reviews → Review service: submits reviews
- Reader → Authentication: signs in
- Reader → Profiles and onboarding: manages profile
- Reader → Privacy settings: sets visibility
- Privacy settings → Supabase and PostgreSQL: persists settings (evidence: `data/user/profile/PrivacySettingsService.ts`)
- Reader → Wishlist and sharing: saves and shares
- Reader → User review management: manages reviews
- User review management → Review service: loads and deletes (evidence: `data/books/reviews/useUserReviews.ts`)
- Review service → Supabase and PostgreSQL: reads and writes (evidence: `data/books/reviews/ReviewService.ts`)
- Reader → Cart experience: adds books
- Cart experience → Cart service: updates cart
- Cart service → Supabase and PostgreSQL: persists cart
- Reader → Checkout form: checks out
- Checkout form → Checkout action: submits checkout (evidence: `app/checkout/useCheckoutForm.ts`)
- Checkout action → Checkout orchestration: executes checkout
- Checkout orchestration → Stripe payments: creates intent (evidence: `data/checkout/services/CheckoutService.ts`)
- Checkout orchestration → Order repository: persists order (evidence: `data/checkout/services/CheckoutService.ts`)
- Order repository → Supabase and PostgreSQL: stores order
- Reader → Order views: views order
- Payment webhook and reconciliation → Stripe payments: processes events (evidence: `app/api/webhooks/stripe/route.ts`)
- Payment webhook and reconciliation → Supabase and PostgreSQL: updates payment state
- Book repository → Database types: uses database types (evidence: `data/books/BookService.ts`)
- Order repository → Database types: uses database types (evidence: `data/checkout/repositories/CheckoutOrderRepository.ts`)