# fjdvm/brenraphaels-ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/fjdvm/brenraphaels-ecommerce
- Repository: https://github.com/fjdvm/brenraphaels-ecommerce

## Overview

Bren Raphael’s Ube Jam & Halaya site combines a public storefront with customer accounts, shopping, order and support services, plus a distinct careers portal. A shopper discovers products, builds a cart, checks out, and manages orders; applicants browse roles, apply, and track applications. The graph also preserves assistant handoff, feedback, returns, and address lookup as separate capabilities. Solid edges reflect excerpts or SOURCE INDEX references; dashed edges mark product relationships whose runtime wiring was not shown in the sampled source.

Main entry points: [`lib/db/index.ts`](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/db/index.ts) (Application Database), [`lib/customer/current-visitor.ts`](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/customer/current-visitor.ts) (Visitor Resolution), [`app/(careers)/careers/(portal)/page.tsx`](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(careers)/careers/(portal)/page.tsx) (Careers & Job Search), [`app/(careers)/careers/(portal)/applications/page.tsx`](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(careers)/careers/(portal)/applications/page.tsx) (Application Tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront &amp; Catalog"]
  node_home["Home &amp; Editorial<br/>[page.tsx]"]
  node_catalog["Product Catalog"]
  node_product_pages["Product Pages<br/>[page.tsx]"]
end

subgraph group_customer["Customer &amp; Commerce"]
  node_sign_in["Customer Sign-in<br/>[sign-in-form.tsx]"]
  node_visitor["Visitor Resolution<br/>[current-visitor.ts]"]
  node_cart["Cart &amp; Checkout<br/>[checkout.tsx]"]
  node_order_management["Orders &amp; Delivery<br/>[orders.ts]"]
  node_returns["Returns<br/>[returns.ts]"]
  node_profile["Customer Profile<br/>[page.tsx]"]
end

subgraph group_careers["Careers Portal"]
  node_careers_portal["Careers &amp; Job Search<br/>[page.tsx]"]
  node_job_postings["Job Postings<br/>[job-postings.ts]"]
  node_applications["Applications<br/>[applications.ts]"]
  node_application_tracking["Application Tracking<br/>[page.tsx]"]
end

subgraph group_services["Support &amp; Services"]
  node_assistant["Assistant Chat<br/>[route.ts]"]
  node_handoff["Assistant Handoff<br/>[handoff.ts]"]
  node_support["Support Tickets<br/>[tickets.ts]"]
  node_feedback["Feedback Reports<br/>[route.ts]"]
  node_address_lookup["Address Lookup<br/>[index.ts]"]
end

subgraph group_data["Identity &amp; Persistence"]
  node_auth_service["Neon Auth<br/>[server.ts]"]
  node_database[("Application Database<br/>[index.ts]")]
  node_careers_database[("Careers Database<br/>[db.ts]")]
end

node_shopper(("Shopper"))
node_github{{"GitHub Issues"}}

node_shopper -.->|"browses"| node_home
node_home -->|"features products"| node_catalog
node_shopper -.->|"views products"| node_product_pages
node_product_pages -.->|"loads product data"| node_catalog
node_shopper -.->|"signs in"| node_sign_in
node_sign_in -.->|"authenticates"| node_visitor
node_visitor -->|"gets session"| node_auth_service
node_visitor -->|"classifies visitor"| node_database
node_shopper -.->|"shops"| node_cart
node_cart -.->|"places order"| node_order_management
node_shopper -.->|"manages orders"| node_order_management
node_shopper -.->|"requests return"| node_returns
node_shopper -.->|"manages profile"| node_profile
node_shopper -.->|"browses roles"| node_careers_portal
node_careers_portal -->|"lists openings"| node_job_postings
node_careers_portal -->|"opens database"| node_careers_database
node_shopper -.->|"submits application"| node_applications
node_applications -->|"uses posting data"| node_job_postings
node_shopper -.->|"tracks application"| node_application_tracking
node_application_tracking -->|"loads applications"| node_applications
node_application_tracking -->|"reads careers data"| node_careers_database
node_shopper -.->|"asks assistant"| node_assistant
node_assistant -.->|"prepares handoff"| node_handoff
node_shopper -.->|"requests support"| node_support
node_shopper -.->|"submits feedback"| node_feedback
node_feedback -->|"rate limits"| node_database
node_feedback -->|"creates issue"| node_github
node_shopper -.->|"selects address"| node_address_lookup
node_address_lookup -.->|"validates address"| node_database
node_database -.->|"separate stores"| node_careers_database

click node_home "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(site)/page.tsx"
click node_catalog "https://github.com/fjdvm/brenraphaels-ecommerce/tree/main/lib/catalog"
click node_product_pages "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(site)/products/%5Bslug%5D/page.tsx"
click node_sign_in "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/components/features/auth/sign-in-form.tsx"
click node_visitor "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/customer/current-visitor.ts"
click node_cart "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/components/features/orders/checkout.tsx"
click node_order_management "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/orders/orders.ts"
click node_returns "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/returns/returns.ts"
click node_profile "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(site)/(protected)/profile/page.tsx"
click node_careers_portal "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(careers)/careers/(portal)/page.tsx"
click node_job_postings "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/careers/job-postings.ts"
click node_applications "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/careers/applications.ts"
click node_application_tracking "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(careers)/careers/(portal)/applications/page.tsx"
click node_assistant "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/api/assistant/messages/route.ts"
click node_handoff "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/assistant-handoff/handoff.ts"
click node_support "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/support/tickets.ts"
click node_feedback "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/api/feedback/route.ts"
click node_address_lookup "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/psgc/index.ts"
click node_auth_service "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/neon-auth/server.ts"
click node_database "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/db/index.ts"
click node_careers_database "https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/careers/db.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_home,node_catalog,node_product_pages toneBlue
class node_sign_in,node_visitor,node_cart,node_order_management,node_returns,node_profile toneAmber
class node_careers_portal,node_job_postings,node_applications,node_application_tracking toneMint
class node_assistant,node_handoff,node_support,node_feedback,node_address_lookup toneRose
class node_auth_service,node_database,node_careers_database,node_shopper,node_github toneIndigo
```

## Components

### Storefront & Catalog

- [Home & Editorial](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(site)/page.tsx): `app/(site)/page.tsx`
- [Product Catalog](https://github.com/fjdvm/brenraphaels-ecommerce/tree/main/lib/catalog): `lib/catalog`
- [Product Pages](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(site)/products/%5Bslug%5D/page.tsx): `app/(site)/products/[slug]/page.tsx`

### Customer & Commerce

- [Customer Sign-in](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/components/features/auth/sign-in-form.tsx): `components/features/auth/sign-in-form.tsx`
- [Visitor Resolution](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/customer/current-visitor.ts): `lib/customer/current-visitor.ts`
- [Cart & Checkout](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/components/features/orders/checkout.tsx): `components/features/orders/checkout.tsx`
- [Orders & Delivery](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/orders/orders.ts): `lib/orders/orders.ts`
- [Returns](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/returns/returns.ts): `lib/returns/returns.ts`
- [Customer Profile](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(site)/(protected)/profile/page.tsx): `app/(site)/(protected)/profile/page.tsx`

### Careers Portal

- [Careers & Job Search](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(careers)/careers/(portal)/page.tsx): `app/(careers)/careers/(portal)/page.tsx`
- [Job Postings](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/careers/job-postings.ts): `lib/careers/job-postings.ts`
- [Applications](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/careers/applications.ts): `lib/careers/applications.ts`
- [Application Tracking](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/(careers)/careers/(portal)/applications/page.tsx): `app/(careers)/careers/(portal)/applications/page.tsx`

### Support & Services

- [Assistant Chat](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/api/assistant/messages/route.ts): `app/api/assistant/messages/route.ts`
- [Assistant Handoff](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/assistant-handoff/handoff.ts): `lib/assistant-handoff/handoff.ts`
- [Support Tickets](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/support/tickets.ts): `lib/support/tickets.ts`
- [Feedback Reports](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/app/api/feedback/route.ts): `app/api/feedback/route.ts`
- [Address Lookup](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/psgc/index.ts): `lib/psgc/index.ts`

### Identity & Persistence

- [Neon Auth](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/neon-auth/server.ts): `lib/neon-auth/server.ts`
- [Application Database](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/db/index.ts): `lib/db/index.ts`
- [Careers Database](https://github.com/fjdvm/brenraphaels-ecommerce/blob/main/lib/careers/db.ts): `lib/careers/db.ts`

### Other components

- **Shopper**
- **GitHub Issues**

## Connections

- Shopper → Home & Editorial: browses
- Home & Editorial → Product Catalog: features products (evidence: `app/(site)/page.tsx`)
- Shopper → Product Pages: views products
- Product Pages → Product Catalog: loads product data
- Shopper → Customer Sign-in: signs in
- Customer Sign-in → Visitor Resolution: authenticates
- Visitor Resolution → Neon Auth: gets session (evidence: `lib/customer/current-visitor.ts`)
- Visitor Resolution → Application Database: classifies visitor (evidence: `lib/customer/current-visitor.ts`)
- Shopper → Cart & Checkout: shops
- Cart & Checkout → Orders & Delivery: places order
- Shopper → Orders & Delivery: manages orders
- Shopper → Returns: requests return
- Shopper → Customer Profile: manages profile
- Shopper → Careers & Job Search: browses roles
- Careers & Job Search → Job Postings: lists openings (evidence: `app/(careers)/careers/(portal)/page.tsx`)
- Careers & Job Search → Careers Database: opens database (evidence: `app/(careers)/careers/(portal)/page.tsx`)
- Shopper → Applications: submits application
- Applications → Job Postings: uses posting data (evidence: `lib/careers/applications.ts`)
- Shopper → Application Tracking: tracks application
- Application Tracking → Applications: loads applications (evidence: `app/(careers)/careers/(portal)/applications/page.tsx`)
- Application Tracking → Careers Database: reads careers data (evidence: `app/(careers)/careers/(portal)/applications/page.tsx`)
- Shopper → Assistant Chat: asks assistant
- Assistant Chat → Assistant Handoff: prepares handoff
- Shopper → Support Tickets: requests support
- Shopper → Feedback Reports: submits feedback
- Feedback Reports → Application Database: rate limits (evidence: `app/api/feedback/route.ts`)
- Feedback Reports → GitHub Issues: creates issue (evidence: `app/api/feedback/route.ts`)
- Shopper → Address Lookup: selects address
- Address Lookup → Application Database: validates address
- Application Database → Careers Database: separate stores
