# saksham953/book-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/saksham953/book-buddy
- Repository: https://github.com/saksham953/book-buddy

## Overview

BookBuddy is a Next.js/React bookstore backed by a Flask API and AWS services. The intended customer journey is discovery and cart building, Stripe checkout, then order tracking; admins also manage the catalog. The sampled webhook does not create backend orders, while the orders page excerpt builds a local order after checkout success, so the documented end-to-end flow is not fully wired in the shown code. Connections for unsampled features follow README documentation rather than inspected implementation.

Main entry points: [`backend/app.py`](https://github.com/saksham953/book-buddy/blob/main/backend/app.py) (Flask API), [`book/app/page.tsx`](https://github.com/saksham953/book-buddy/blob/main/book/app/page.tsx) (Landing page), [`book/app/api/checkout/route.ts`](https://github.com/saksham953/book-buddy/blob/main/book/app/api/checkout/route.ts) (Checkout route), [`book/app/browse/page.tsx`](https://github.com/saksham953/book-buddy/blob/main/book/app/browse/page.tsx) (Book discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_hero["Hero experience"]
  node_features["Feature cards<br/>[features-2.tsx]"]
  node_testimonials["Testimonials<br/>[testimonial-v2.tsx]"]
  node_browse["Book discovery<br/>[page.tsx]"]
  node_admin["Catalog admin<br/>[page.tsx]"]
end

subgraph group_commerce["Commerce"]
  node_checkout["Checkout route<br/>[route.ts]"]
  node_stripe{{"Stripe Checkout"}}
  node_webhook["Stripe webhook<br/>[route.ts]"]
  node_orders["Order tracking<br/>[page.tsx]"]
end

subgraph group_backend["Backend API"]
  node_flask["Flask API<br/>[app.py]"]
  node_catalog["Catalog endpoints<br/>[app.py]"]
  node_orderapi["Order endpoints<br/>[app.py]"]
end

subgraph group_cloud["Cloud Services"]
  node_dynamodb[("DynamoDB")]
  node_sns["AWS SNS"]
  node_clerk{{"Clerk auth"}}
end

node_reader(("Reader"))

node_reader -->|"visits"| node_landing
node_landing -->|"renders"| node_hero
node_landing -->|"renders"| node_features
node_landing -->|"renders"| node_testimonials
node_hero -->|"links to"| node_browse
node_reader -->|"discovers books"| node_browse
node_browse -.->|"requests catalog"| node_flask
node_reader -->|"starts checkout"| node_checkout
node_checkout -->|"checks identity"| node_clerk
node_checkout -->|"creates session"| node_stripe
node_stripe -->|"posts event"| node_webhook
node_webhook -.->|"would submit order"| node_flask
node_reader -->|"views tracking"| node_orders
node_orders -.->|"requests order history"| node_flask
node_admin -->|"checks identity"| node_clerk
node_admin -->|"manages books"| node_flask
node_flask -->|"routes requests"| node_catalog
node_flask -->|"routes requests"| node_orderapi
node_catalog -->|"scans and writes"| node_dynamodb
node_orderapi -->|"reads and writes"| node_dynamodb
node_orderapi -->|"publishes order alert"| node_sns

click node_landing "https://github.com/saksham953/book-buddy/blob/main/book/app/page.tsx"
click node_hero "https://github.com/saksham953/book-buddy/blob/main/book/components/ui/cinematic-landing-hero.tsx"
click node_features "https://github.com/saksham953/book-buddy/blob/main/book/components/blocks/features-2.tsx"
click node_testimonials "https://github.com/saksham953/book-buddy/blob/main/book/components/ui/testimonial-v2.tsx"
click node_browse "https://github.com/saksham953/book-buddy/blob/main/book/app/browse/page.tsx"
click node_admin "https://github.com/saksham953/book-buddy/blob/main/book/app/admin/page.tsx"
click node_checkout "https://github.com/saksham953/book-buddy/blob/main/book/app/api/checkout/route.ts"
click node_webhook "https://github.com/saksham953/book-buddy/blob/main/book/app/api/webhooks/stripe/route.ts"
click node_orders "https://github.com/saksham953/book-buddy/blob/main/book/app/orders/page.tsx"
click node_flask "https://github.com/saksham953/book-buddy/blob/main/backend/app.py"
click node_catalog "https://github.com/saksham953/book-buddy/blob/main/backend/app.py"
click node_orderapi "https://github.com/saksham953/book-buddy/blob/main/backend/app.py"

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_landing,node_hero,node_features,node_testimonials,node_browse,node_admin toneBlue
class node_checkout,node_stripe,node_webhook,node_orders toneAmber
class node_flask,node_catalog,node_orderapi toneMint
class node_dynamodb,node_sns,node_clerk toneRose
class node_reader toneIndigo
```

## Components

### Storefront

- [Landing page](https://github.com/saksham953/book-buddy/blob/main/book/app/page.tsx): `book/app/page.tsx`
- [Hero experience](https://github.com/saksham953/book-buddy/blob/main/book/components/ui/cinematic-landing-hero.tsx): `book/components/ui/cinematic-landing-hero.tsx`
- [Feature cards](https://github.com/saksham953/book-buddy/blob/main/book/components/blocks/features-2.tsx): `book/components/blocks/features-2.tsx`
- [Testimonials](https://github.com/saksham953/book-buddy/blob/main/book/components/ui/testimonial-v2.tsx): `book/components/ui/testimonial-v2.tsx`
- [Book discovery](https://github.com/saksham953/book-buddy/blob/main/book/app/browse/page.tsx): `book/app/browse/page.tsx`
- [Catalog admin](https://github.com/saksham953/book-buddy/blob/main/book/app/admin/page.tsx): `book/app/admin/page.tsx`

### Commerce

- [Checkout route](https://github.com/saksham953/book-buddy/blob/main/book/app/api/checkout/route.ts): `book/app/api/checkout/route.ts`
- **Stripe Checkout**
- [Stripe webhook](https://github.com/saksham953/book-buddy/blob/main/book/app/api/webhooks/stripe/route.ts): `book/app/api/webhooks/stripe/route.ts`
- [Order tracking](https://github.com/saksham953/book-buddy/blob/main/book/app/orders/page.tsx): `book/app/orders/page.tsx`

### Backend API

- [Flask API](https://github.com/saksham953/book-buddy/blob/main/backend/app.py): `backend/app.py`
- [Catalog endpoints](https://github.com/saksham953/book-buddy/blob/main/backend/app.py): `backend/app.py`
- [Order endpoints](https://github.com/saksham953/book-buddy/blob/main/backend/app.py): `backend/app.py`

### Cloud Services

- **DynamoDB**
- **AWS SNS**
- **Clerk auth**

### Other components

- **Reader**

## Connections

- Reader → Landing page: visits (evidence: `README.md`)
- Landing page → Hero experience: renders (evidence: `book/app/page.tsx`)
- Landing page → Feature cards: renders (evidence: `book/app/page.tsx`)
- Landing page → Testimonials: renders (evidence: `book/app/page.tsx`)
- Hero experience → Book discovery: links to (evidence: `book/components/ui/cinematic-landing-hero.tsx`)
- Reader → Book discovery: discovers books (evidence: `README.md`)
- Book discovery → Flask API: requests catalog (evidence: `README.md`)
- Reader → Checkout route: starts checkout
- Checkout route → Clerk auth: checks identity (evidence: `book/app/api/checkout/route.ts`)
- Checkout route → Stripe Checkout: creates session (evidence: `book/app/api/checkout/route.ts`)
- Stripe Checkout → Stripe webhook: posts event (evidence: `README.md`)
- Stripe webhook → Flask API: would submit order
- Reader → Order tracking: views tracking (evidence: `README.md`)
- Order tracking → Flask API: requests order history (evidence: `README.md`)
- Catalog admin → Clerk auth: checks identity (evidence: `book/app/admin/page.tsx`)
- Catalog admin → Flask API: manages books (evidence: `book/app/admin/page.tsx`)
- Flask API → Catalog endpoints: routes requests (evidence: `backend/app.py`)
- Flask API → Order endpoints: routes requests (evidence: `backend/app.py`)
- Catalog endpoints → DynamoDB: scans and writes (evidence: `backend/app.py`)
- Order endpoints → DynamoDB: reads and writes (evidence: `backend/app.py`)
- Order endpoints → AWS SNS: publishes order alert (evidence: `backend/app.py`)
