# fahryerlang/bookstore architecture

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

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

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application organized as a bookstore / commerce site with three major surfaces: a **public storefront**, a **signed-in user area**, and an **admin back office**.
   - The codebase is split between route segments under `app/`, reusable UI in `components/`, and server-side domain logic in `lib/`.

2. **Route architecture**
   - `app/layout.tsx` and `app/globals.css` define the global shell and styling.
   - Top-level routes cover the marketing/public experience (`app/page.tsx`, `about`, `contact`, `login`, `register`, `books/[id]`, `cart`, `checkout`) plus authenticated areas (`dashboard`, `profile`) and management areas (`admin`).
   - The route tree suggests the app uses nested layouts to provide different shells for cart, checkout, dashboard, and admin sections.

3. **Public storefront flow**
   - The store front is centered around **book discovery and purchase**:
     - `app/page.tsx` for the landing page
     - `app/books/[id]/page.tsx` for product detail
     - `app/cart/page.tsx` for cart review
     - `app/checkout/page.tsx` and `app/checkout/success/page.tsx` for order completion
   - `app/books/[id]/AddToCartButton.tsx` is the main user action connecting product pages to the cart subsystem.

4. **Cart and checkout boundary**
   - Cart and checkout are isolated into their own route layouts (`app/cart/layout.tsx`, `app/checkout/layout.tsx`), which indicates a distinct purchase flow separate from the general site chrome.
   - `app/cart/CartItemRow.tsx` and `app/checkout/CheckoutForm.tsx` show the UI is split into item-level cart rendering and a dedicated checkout submission step.

5. **Authenticated user area**
   - `app/dashboard/*` and `app/profile/page.tsx` form the signed-in user area.
   - `components/UserPanelShell.tsx` and `components/UserSidebar.tsx` imply a shared authenticated layout/navigation pattern.
   - `components/ProfileOverview.tsx` suggests the profile/dashboard pages aggregate account-related data rather than presenting only isolated forms.

6. **Admin back office**
   - `app/admin/*` is a separate operational interface for managing core business entities:
     - books
     - categories
     - orders
     - messages
     - users
     - profile
   - `components/AdminSidebar.tsx` and `app/admin/layout.tsx` indicate a dedicated admin shell with its own navigation and access boundary.
   - CRUD-oriented UI exists for content management, such as book creation/editing, category forms, delete buttons, and order status updates.

7. **Domain modules and server actions**
   - The `lib/actions/` folder is the main server-side application layer.
   - Separate action modules exist for `auth`, `books`, `cart`, `categories`, `messages`, and `orders`, which indicates the business logic is organized by domain rather than by UI page.
   - This structure implies the UI routes call into these action modules for mutations and possibly data retrieval.

8. **Data model and persistence**
   - Prisma is the persistence layer:
     - `prisma/schema.prisma` defines the data model
     - `prisma/seed.ts` provides initial data
     - `lib/prisma.ts` centralizes the Prisma client
   - The domain naming strongly suggests entities for books, categories, orders, messages, users, and authentication-related records.
   - `prisma.config.ts` shows Prisma is configured as a first-class build/runtime dependency.

9. **Authentication and access control**
   - `lib/auth.ts`, `lib/actions/auth.ts`, and `proxy.ts` indicate an authentication and route-protection layer.
   - The presence of `proxy.ts` suggests requests are filtered before reaching protected routes, likely to enforce login/admin access and possibly redirect unauthenticated users.
   - The app is therefore not just a public catalog; it has role-aware sections with restricted capabilities.

10. **Shared presentation layer**
   - `components/` contains reusable UI used across many routes:
     - `Navbar`, `Footer`, `BrandLogo`
     - `Button`, `BookCard`, `SearchBar`
     - sidebar/layout helpers for admin and user areas
     - `components/icons.tsx` for iconography
   - This indicates the app’s visual structure is component-driven, with most pages assembling shared primitives rather than duplicating layout code.

11. **Operational workflows**
   - The admin paths show the main business workflows:
     - create/edit/delete books
     - manage categories
     - inspect and delete messages
     - update order status
     - browse users
   - Those workflows are likely backed by server actions and Prisma writes, with the UI acting as a thin control surface over the database.

12. **Technology/runtime signals**
   - The project is built with **Next.js**, TypeScript, and Tailwind/PostCSS styling (`postcss.config.mjs`, `app/globals.css`).
   - Package management is set up for Bun as well (`bun.lock`), though the project is still compatible with standard Next.js dev commands.
   - Deployment/runtime assumptions are Vercel-friendly, matching the Next.js template baseline.

13. **For an architecture diagram**
   - The clearest diagram would show:
     - **Browser/UI layer**: public pages, dashboard, admin
     - **Next.js route/layout layer**: nested shells and page routes
     - **Server action layer**: domain-specific mutations/queries in `lib/actions`
     - **Auth/access control layer**: auth utilities plus route proxying
     - **Persistence layer**: Prisma and the relational database
   - The main data flow is: user interaction in a route page/component → server action → Prisma-backed data store → updated UI state/rendering.

Main entry points: [`lib/actions/orders.ts`](https://github.com/fahryerlang/bookstore/blob/master/lib/actions/orders.ts) (Orders actions), [`lib/prisma.ts`](https://github.com/fahryerlang/bookstore/blob/master/lib/prisma.ts) (Prisma client), [`lib/auth.ts`](https://github.com/fahryerlang/bookstore/blob/master/lib/auth.ts) (Auth guard), [`app/dashboard/layout.tsx`](https://github.com/fahryerlang/bookstore/blob/master/app/dashboard/layout.tsx) (User shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public storefront"]
  node_app_layout["App shell<br/>next layout<br/>[layout.tsx]"]
  node_app_home["Home<br/>route page<br/>[page.tsx]"]
  node_app_book_detail["Book page<br/>route page<br/>[page.tsx]"]
  node_app_cart_layout["Cart shell<br/>route layout<br/>[layout.tsx]"]
  node_app_cart_page["Cart<br/>route page<br/>[page.tsx]"]
  node_app_checkout_layout["Checkout shell<br/>route layout<br/>[layout.tsx]"]
  node_app_checkout_page["Checkout<br/>route page<br/>[page.tsx]"]
end

subgraph group_group_account["Account area"]
  node_app_account_layout["User shell<br/>route layout<br/>[layout.tsx]"]
  node_app_dashboard["Dashboard<br/>route page<br/>[page.tsx]"]
  node_app_profile["Profile<br/>route page<br/>[page.tsx]"]
end

subgraph group_group_admin["Admin back office"]
  node_app_admin_layout["Admin shell<br/>route layout<br/>[layout.tsx]"]
  node_app_admin_home["Admin home<br/>route page<br/>[page.tsx]"]
end

subgraph group_group_shared["Shared UI"]
  node_components_navbar["Navbar<br/>ui component<br/>[Navbar.tsx]"]
  node_components_user_shell["User panel<br/>ui shell<br/>[UserPanelShell.tsx]"]
end

subgraph group_group_server["Server domain"]
  node_lib_books_actions["Books actions<br/>server actions<br/>[books.ts]"]
  node_lib_orders_actions["Orders actions<br/>server actions<br/>[orders.ts]"]
  node_lib_auth_actions["Auth actions<br/>server actions<br/>[auth.ts]"]
  node_lib_auth["Auth guard<br/>auth util<br/>[auth.ts]"]
  node_proxy["Route proxy<br/>edge guard<br/>[proxy.ts]"]
end

subgraph group_group_data["Persistence"]
  node_lib_prisma[("Prisma client<br/>data client<br/>[prisma.ts]")]
  node_schema_prisma["Schema<br/>data model<br/>[schema.prisma]"]
end

node_app_layout -->|"renders"| node_components_navbar
node_app_layout -->|"wraps"| node_app_home
node_app_home -.->|"reads"| node_lib_books_actions
node_app_book_detail -.->|"reads"| node_lib_books_actions
node_app_book_detail -->|"adds to cart"| node_lib_orders_actions
node_app_cart_page -.->|"updates"| node_lib_orders_actions
node_app_checkout_page -->|"submits"| node_lib_orders_actions
node_app_cart_layout -->|"wraps"| node_app_cart_page
node_app_checkout_layout -->|"wraps"| node_app_checkout_page
node_app_account_layout -->|"renders"| node_components_user_shell
node_app_account_layout -->|"wraps"| node_app_dashboard
node_app_account_layout -->|"wraps"| node_app_profile
node_app_dashboard -.->|"guards"| node_lib_auth
node_app_profile -.->|"guards"| node_lib_auth
node_app_admin_layout -->|"wraps"| node_app_admin_home
node_app_admin_layout -.->|"protected by"| node_proxy
node_proxy -.->|"uses"| node_lib_auth
node_lib_auth_actions -->|"uses"| node_lib_auth
node_lib_books_actions -->|"queries"| node_lib_prisma
node_lib_orders_actions -->|"writes"| node_lib_prisma
node_lib_auth_actions -->|"writes"| node_lib_prisma
node_lib_prisma -->|"implements"| node_schema_prisma

click node_app_layout "https://github.com/fahryerlang/bookstore/blob/master/app/layout.tsx"
click node_app_home "https://github.com/fahryerlang/bookstore/blob/master/app/page.tsx"
click node_app_book_detail "https://github.com/fahryerlang/bookstore/blob/master/app/books/[id]/page.tsx"
click node_app_cart_layout "https://github.com/fahryerlang/bookstore/blob/master/app/cart/layout.tsx"
click node_app_cart_page "https://github.com/fahryerlang/bookstore/blob/master/app/cart/page.tsx"
click node_app_checkout_layout "https://github.com/fahryerlang/bookstore/blob/master/app/checkout/layout.tsx"
click node_app_checkout_page "https://github.com/fahryerlang/bookstore/blob/master/app/checkout/page.tsx"
click node_app_account_layout "https://github.com/fahryerlang/bookstore/blob/master/app/dashboard/layout.tsx"
click node_app_dashboard "https://github.com/fahryerlang/bookstore/blob/master/app/dashboard/page.tsx"
click node_app_profile "https://github.com/fahryerlang/bookstore/blob/master/app/profile/page.tsx"
click node_app_admin_layout "https://github.com/fahryerlang/bookstore/blob/master/app/admin/layout.tsx"
click node_app_admin_home "https://github.com/fahryerlang/bookstore/blob/master/app/admin/page.tsx"
click node_components_navbar "https://github.com/fahryerlang/bookstore/blob/master/components/Navbar.tsx"
click node_components_user_shell "https://github.com/fahryerlang/bookstore/blob/master/components/UserPanelShell.tsx"
click node_lib_books_actions "https://github.com/fahryerlang/bookstore/blob/master/lib/actions/books.ts"
click node_lib_orders_actions "https://github.com/fahryerlang/bookstore/blob/master/lib/actions/orders.ts"
click node_lib_auth_actions "https://github.com/fahryerlang/bookstore/blob/master/lib/actions/auth.ts"
click node_lib_auth "https://github.com/fahryerlang/bookstore/blob/master/lib/auth.ts"
click node_lib_prisma "https://github.com/fahryerlang/bookstore/blob/master/lib/prisma.ts"
click node_schema_prisma "https://github.com/fahryerlang/bookstore/blob/master/prisma/schema.prisma"
click node_proxy "https://github.com/fahryerlang/bookstore/blob/master/proxy.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_app_layout,node_app_home,node_app_book_detail,node_app_cart_layout,node_app_cart_page,node_app_checkout_layout,node_app_checkout_page toneBlue
class node_app_account_layout,node_app_dashboard,node_app_profile toneAmber
class node_app_admin_layout,node_app_admin_home toneMint
class node_components_navbar,node_components_user_shell toneRose
class node_lib_books_actions,node_lib_orders_actions,node_lib_auth_actions,node_lib_auth,node_proxy toneIndigo
class node_lib_prisma,node_schema_prisma toneTeal
```

## Components

### Public storefront

Marketing, browsing, cart, and checkout routes.

- [App shell](https://github.com/fahryerlang/bookstore/blob/master/app/layout.tsx): next layout · Global app layout and chrome. · `app/layout.tsx`
- [Home](https://github.com/fahryerlang/bookstore/blob/master/app/page.tsx): route page · Public landing page. · `app/page.tsx`
- [Book page](https://github.com/fahryerlang/bookstore/blob/master/app/books/[id]/page.tsx): route page · Product detail and purchase entry point. · `app/books/[id]/page.tsx`
- [Cart shell](https://github.com/fahryerlang/bookstore/blob/master/app/cart/layout.tsx): route layout · Dedicated cart flow layout. · `app/cart/layout.tsx`
- [Cart](https://github.com/fahryerlang/bookstore/blob/master/app/cart/page.tsx): route page · Cart review and item editing. · `app/cart/page.tsx`
- [Checkout shell](https://github.com/fahryerlang/bookstore/blob/master/app/checkout/layout.tsx): route layout · Dedicated checkout flow layout. · `app/checkout/layout.tsx`
- [Checkout](https://github.com/fahryerlang/bookstore/blob/master/app/checkout/page.tsx): route page · Checkout form and submission step. · `app/checkout/page.tsx`

### Account area

Signed-in user routes and shared shell.

- [User shell](https://github.com/fahryerlang/bookstore/blob/master/app/dashboard/layout.tsx): route layout · Authenticated user area layout. · `app/dashboard/layout.tsx`
- [Dashboard](https://github.com/fahryerlang/bookstore/blob/master/app/dashboard/page.tsx): route page · Signed-in user overview. · `app/dashboard/page.tsx`
- [Profile](https://github.com/fahryerlang/bookstore/blob/master/app/profile/page.tsx): route page · Public/user profile page. · `app/profile/page.tsx`

### Admin back office

Operational management routes and actions.

- [Admin shell](https://github.com/fahryerlang/bookstore/blob/master/app/admin/layout.tsx): route layout · Admin-specific layout and navigation. · `app/admin/layout.tsx`
- [Admin home](https://github.com/fahryerlang/bookstore/blob/master/app/admin/page.tsx): route page · Admin landing page. · `app/admin/page.tsx`

### Shared UI

Reusable presentation components used across routes.

- [Navbar](https://github.com/fahryerlang/bookstore/blob/master/components/Navbar.tsx): ui component · Primary site navigation. · `components/Navbar.tsx`
- [User panel](https://github.com/fahryerlang/bookstore/blob/master/components/UserPanelShell.tsx): ui shell · Authenticated user navigation shell. · `components/UserPanelShell.tsx`

### Server domain

Server actions and auth utilities.

- [Books actions](https://github.com/fahryerlang/bookstore/blob/master/lib/actions/books.ts): server actions · Book data and mutation logic. · `lib/actions/books.ts`
- [Orders actions](https://github.com/fahryerlang/bookstore/blob/master/lib/actions/orders.ts): server actions · Order creation and status workflows. · `lib/actions/orders.ts`
- [Auth actions](https://github.com/fahryerlang/bookstore/blob/master/lib/actions/auth.ts): server actions · Login, register, and session flows. · `lib/actions/auth.ts`
- [Auth guard](https://github.com/fahryerlang/bookstore/blob/master/lib/auth.ts): auth util · Authentication and access-control helpers. · `lib/auth.ts`
- [Route proxy](https://github.com/fahryerlang/bookstore/blob/master/proxy.ts): edge guard · Pre-route protection and redirects. · `proxy.ts`

### Persistence

Prisma schema and database access layer.

- [Prisma client](https://github.com/fahryerlang/bookstore/blob/master/lib/prisma.ts): data client · Central Prisma database client. · `lib/prisma.ts`
- [Schema](https://github.com/fahryerlang/bookstore/blob/master/prisma/schema.prisma): data model · Database model definitions. · `prisma/schema.prisma`

## Connections

- App shell → Navbar: renders · Global shell composes shared navigation.
- App shell → Home: wraps · Provides the root app chrome.
- Home → Books actions: reads · Landing page surfaces catalog data.
- Book page → Books actions: reads · Book page loads product details.
- Book page → Orders actions: adds to cart · Primary purchase action starts here.
- Cart → Orders actions: updates · Cart reflects purchase state.
- Checkout → Orders actions: submits · Checkout creates/completes orders.
- Cart shell → Cart: wraps · Dedicated cart flow layout.
- Checkout shell → Checkout: wraps · Dedicated checkout flow layout.
- User shell → User panel: renders · Authenticated area uses shared user shell.
- User shell → Dashboard: wraps · User layout contains dashboard routes.
- User shell → Profile: wraps · User layout contains profile route.
- Dashboard → Auth guard: guards · Signed-in area depends on auth state.
- Profile → Auth guard: guards · Profile access is role/session aware.
- Admin shell → Admin home: wraps · Admin shell contains operational routes.
- Admin shell → Route proxy: protected by · Admin entry is filtered before routing.
- Route proxy → Auth guard: uses · Edge guard consults auth/session logic.
- Auth actions → Auth guard: uses · Authentication actions build on auth helpers.
- Books actions → Prisma client: queries · Book actions read/write through Prisma.
- Orders actions → Prisma client: writes · Order workflows persist through Prisma.
- Auth actions → Prisma client: writes · Auth flows persist user/session data.
- Prisma client → Schema: implements · Prisma client is generated from schema.
