# saadullah990123/veloura-naturals architecture

> Architecture diagram of the GitHub repository saadullah990123/veloura-naturals, 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/saadullah990123/veloura-naturals
- Repository: https://github.com/saadullah990123/veloura-naturals

## Overview

Veloura Naturals is a single-product direct-to-consumer storefront with an admin management hub. Customers browse product and review content, submit orders, track them, or contact the business; admins authenticate and manage products, orders, reviews, account details, and business settings. Order creation validates input, checks live stock and settings, calculates totals server-side, and persists the order atomically. PostgreSQL-backed data access, validation, authentication, and rate limiting support these workflows. The README documents major capabilities whose route implementations were not sampled; their links are shown only where documented, and unsampled internal call paths are not inferred.

Main entry points: [`src/lib/db/index.ts`](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/db/index.ts) (PostgreSQL), [`src/app/api/orders/route.ts`](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/orders/route.ts) (Order creation), [`src/app/api/reviews/route.ts`](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/reviews/route.ts) (Review submission), [`src/app/api/admin`](https://github.com/saadullah990123/veloura-naturals/tree/main/src/app/api/admin) (Admin APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Customer storefront"]
  node_home["Home page<br/>[page.tsx]"]
  node_product["Product page<br/>[page.tsx]"]
  node_reviews_ui["Review display"]
  node_review_parts["Review dialogs<br/>[review-modal.tsx]"]
  node_contact["Contact page<br/>[page.tsx]"]
  node_contact_form["Contact form<br/>[contact-form.tsx]"]
  node_track_page["Track order page<br/>[page.tsx]"]
  node_track_form["Tracking form"]
end

subgraph group_commerce["Commerce workflows"]
  node_order_form["Order form<br/>[order-form.tsx]"]
  node_order_api["Order creation<br/>[route.ts]"]
  node_review_api["Review submission<br/>[route.ts]"]
  node_tracking_api["Order lookup<br/>[route.ts]"]
  node_contact_api["Contact endpoint<br/>[route.ts]"]
end

subgraph group_admin["Admin management"]
  node_admin_login["Admin login<br/>[page.tsx]"]
  node_admin_shell["Admin workspace<br/>[admin-shell.tsx]"]
  node_admin_pages["Management pages"]
  node_admin_product_form["Product editor"]
  node_admin_fetch["Admin API client<br/>[admin-fetch.ts]"]
  node_admin_routes["Admin APIs"]
end

subgraph group_security["Security controls"]
  node_validation["Input validation<br/>[schemas.ts]"]
  node_rate_limit["Rate limiting<br/>[rate-limit.ts]"]
  node_admin_guard["Admin authorization<br/>[require-admin.ts]"]
  node_sessions["Session signing<br/>[session.ts]"]
end

subgraph group_platform["Data platform"]
  node_data_access["Store data access<br/>[data.ts]"]
  node_database[("PostgreSQL<br/>[index.ts]")]
  node_schema["Data schema<br/>[schema.ts]"]
end

node_customer(("Customer"))
node_admin_actor(("Administrator"))

node_customer -->|"browses"| node_home
node_customer -->|"browses"| node_product
node_customer -->|"contacts"| node_contact
node_customer -->|"tracks order"| node_track_page
node_home -->|"loads content"| node_data_access
node_product -->|"loads product"| node_data_access
node_home -->|"renders"| node_reviews_ui
node_reviews_ui -->|"uses dialogs"| node_review_parts
node_product -->|"renders"| node_order_form
node_order_form -.->|"submits order"| node_order_api
node_order_api -->|"validates input"| node_validation
node_order_api -->|"limits attempts"| node_rate_limit
node_order_api -->|"checks and writes"| node_database
node_customer -->|"submits review"| node_review_api
node_review_api -->|"validates input"| node_validation
node_review_api -->|"limits attempts"| node_rate_limit
node_review_api -->|"stores pending review"| node_database
node_contact -->|"renders"| node_contact_form
node_contact_form -.->|"sends message"| node_contact_api
node_contact_api -->|"validates input"| node_validation
node_track_page -.->|"renders"| node_track_form
node_track_form -.->|"looks up order"| node_tracking_api
node_tracking_api -->|"finds orders"| node_data_access
node_data_access -->|"queries records"| node_database
node_database -->|"uses definitions"| node_schema
node_admin_actor -->|"signs in"| node_admin_login
node_admin_actor -->|"manages store"| node_admin_pages
node_admin_login -->|"creates session"| node_sessions
node_admin_shell -.->|"frames workspace"| node_admin_pages
node_admin_pages -->|"calls admin APIs"| node_admin_fetch
node_admin_product_form -->|"sends edits"| node_admin_fetch
node_admin_fetch -.->|"sends requests"| node_admin_routes
node_admin_routes -->|"checks access"| node_admin_guard
node_admin_guard -->|"verifies session"| node_sessions
node_admin_routes -->|"manages records"| node_database
node_admin_routes -->|"validates changes"| node_validation

click node_home "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/page.tsx"
click node_product "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/product/page.tsx"
click node_reviews_ui "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/reviews-section.tsx"
click node_review_parts "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/review-modal.tsx"
click node_contact "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/contact/page.tsx"
click node_contact_form "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/contact-form.tsx"
click node_track_page "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/track-order/page.tsx"
click node_track_form "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/track-order-form.tsx"
click node_order_form "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/order-form.tsx"
click node_order_api "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/orders/route.ts"
click node_review_api "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/reviews/route.ts"
click node_tracking_api "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/track-order/route.ts"
click node_admin_login "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/admin/login/page.tsx"
click node_admin_shell "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/admin/admin-shell.tsx"
click node_admin_pages "https://github.com/saadullah990123/veloura-naturals/tree/main/src/app/admin/(protected)"
click node_admin_product_form "https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/admin/product-form-modal.tsx"
click node_admin_fetch "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/admin-fetch.ts"
click node_admin_routes "https://github.com/saadullah990123/veloura-naturals/tree/main/src/app/api/admin"
click node_contact_api "https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/contact/route.ts"
click node_validation "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/validation/schemas.ts"
click node_rate_limit "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/auth/rate-limit.ts"
click node_admin_guard "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/auth/require-admin.ts"
click node_sessions "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/auth/session.ts"
click node_data_access "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/data.ts"
click node_database "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/db/index.ts"
click node_schema "https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/db/schema.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_product,node_reviews_ui,node_review_parts,node_contact,node_contact_form,node_track_page,node_track_form toneBlue
class node_order_form,node_order_api,node_review_api,node_tracking_api,node_contact_api toneAmber
class node_admin_login,node_admin_shell,node_admin_pages,node_admin_product_form,node_admin_fetch,node_admin_routes toneMint
class node_validation,node_rate_limit,node_admin_guard,node_sessions toneRose
class node_data_access,node_database,node_schema,node_customer,node_admin_actor toneIndigo
```

## Components

### Customer storefront

- [Home page](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Product page](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/product/page.tsx): `src/app/product/page.tsx`
- [Review display](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/reviews-section.tsx): `src/components/reviews-section.tsx`
- [Review dialogs](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/review-modal.tsx): `src/components/review-modal.tsx`
- [Contact page](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/contact/page.tsx): `src/app/contact/page.tsx`
- [Contact form](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/contact-form.tsx): `src/components/contact-form.tsx`
- [Track order page](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/track-order/page.tsx): `src/app/track-order/page.tsx`
- [Tracking form](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/track-order-form.tsx): `src/components/track-order-form.tsx`

### Commerce workflows

- [Order form](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/order-form.tsx): `src/components/order-form.tsx`
- [Order creation](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/orders/route.ts): `src/app/api/orders/route.ts`
- [Review submission](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/reviews/route.ts): `src/app/api/reviews/route.ts`
- [Order lookup](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/track-order/route.ts): `src/app/api/track-order/route.ts`
- [Contact endpoint](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/api/contact/route.ts): `src/app/api/contact/route.ts`

### Admin management

- [Admin login](https://github.com/saadullah990123/veloura-naturals/blob/main/src/app/admin/login/page.tsx): `src/app/admin/login/page.tsx`
- [Admin workspace](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/admin/admin-shell.tsx): `src/components/admin/admin-shell.tsx`
- [Management pages](https://github.com/saadullah990123/veloura-naturals/tree/main/src/app/admin/(protected)): `src/app/admin/(protected)`
- [Product editor](https://github.com/saadullah990123/veloura-naturals/blob/main/src/components/admin/product-form-modal.tsx): `src/components/admin/product-form-modal.tsx`
- [Admin API client](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/admin-fetch.ts): `src/lib/admin-fetch.ts`
- [Admin APIs](https://github.com/saadullah990123/veloura-naturals/tree/main/src/app/api/admin): `src/app/api/admin`

### Security controls

- [Input validation](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/validation/schemas.ts): `src/lib/validation/schemas.ts`
- [Rate limiting](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/auth/rate-limit.ts): `src/lib/auth/rate-limit.ts`
- [Admin authorization](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/auth/require-admin.ts): `src/lib/auth/require-admin.ts`
- [Session signing](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/auth/session.ts): `src/lib/auth/session.ts`

### Data platform

- [Store data access](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/data.ts): `src/lib/data.ts`
- [PostgreSQL](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/db/index.ts): `src/lib/db/index.ts`
- [Data schema](https://github.com/saadullah990123/veloura-naturals/blob/main/src/lib/db/schema.ts): `src/lib/db/schema.ts`

### Other components

- **Customer**
- **Administrator**

## Connections

- Customer → Home page: browses (evidence: `README.md`)
- Customer → Product page: browses (evidence: `README.md`)
- Customer → Contact page: contacts (evidence: `README.md`)
- Customer → Track order page: tracks order (evidence: `README.md`)
- Home page → Store data access: loads content (evidence: `src/app/page.tsx`)
- Product page → Store data access: loads product (evidence: `src/app/product/page.tsx`)
- Home page → Review display: renders (evidence: `src/app/page.tsx`)
- Review display → Review dialogs: uses dialogs (evidence: `src/components/reviews-section.tsx`)
- Product page → Order form: renders (evidence: `src/app/product/page.tsx`)
- Order form → Order creation: submits order
- Order creation → Input validation: validates input (evidence: `src/app/api/orders/route.ts`)
- Order creation → Rate limiting: limits attempts (evidence: `src/app/api/orders/route.ts`)
- Order creation → PostgreSQL: checks and writes (evidence: `src/app/api/orders/route.ts`)
- Customer → Review submission: submits review (evidence: `README.md`)
- Review submission → Input validation: validates input (evidence: `src/app/api/reviews/route.ts`)
- Review submission → Rate limiting: limits attempts (evidence: `src/app/api/reviews/route.ts`)
- Review submission → PostgreSQL: stores pending review (evidence: `src/app/api/reviews/route.ts`)
- Contact page → Contact form: renders (evidence: `src/app/contact/page.tsx`)
- Contact form → Contact endpoint: sends message
- Contact endpoint → Input validation: validates input (evidence: `src/app/api/contact/route.ts`)
- Track order page → Tracking form: renders
- Tracking form → Order lookup: looks up order
- Order lookup → Store data access: finds orders (evidence: `src/app/api/track-order/route.ts`)
- Store data access → PostgreSQL: queries records (evidence: `src/lib/data.ts`)
- PostgreSQL → Data schema: uses definitions (evidence: `src/lib/db/index.ts`)
- Administrator → Admin login: signs in (evidence: `README.md`)
- Administrator → Management pages: manages store (evidence: `README.md`)
- Admin login → Session signing: creates session
- Admin workspace → Management pages: frames workspace
- Management pages → Admin API client: calls admin APIs (evidence: `src/app/admin/(protected)/products/page.tsx`)
- Product editor → Admin API client: sends edits (evidence: `src/components/admin/product-form-modal.tsx`)
- Admin API client → Admin APIs: sends requests
- Admin APIs → Admin authorization: checks access (evidence: `src/app/api/admin/products/route.ts`)
- Admin authorization → Session signing: verifies session (evidence: `src/lib/auth/require-admin.ts`)
- Admin APIs → PostgreSQL: manages records (evidence: `src/app/api/admin/products/route.ts`)
- Admin APIs → Input validation: validates changes (evidence: `src/app/api/admin/products/route.ts`)
