# amalbabu0/ecomerce architecture

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

- Interactive diagram: https://gitdiagram.com/amalbabu0/ecomerce
- Repository: https://github.com/amalbabu0/ecomerce

## Overview

#### Purpose and Runtime
Pavan Foods is a Phase-1 ecommerce storefront for catalog browsing, authenticated accounts, checkout, operations, and security visibility. It runs on Next.js 16 App Router with TypeScript, deployed to Vercel, backed by Supabase and Razorpay. Root application shell and metadata behavior begin at `app/layout.tsx`; route access mediation is centralized in `proxy.ts`.

#### Route Domains and Entry Points
Public storefront routes cover marketing, category/product discovery, cart, and checkout: `app/(marketing)/page.tsx`, `app/(shop)/products/[slug]/page.tsx`, and `app/checkout/page.tsx`. Authenticated account routes provide profiles, addresses, and order history under `app/(account)/account/`. Privileged operations are separately mounted at `app/admin/layout.tsx` and `app/developer/layout.tsx`, with role enforcement both at routing and server/page boundaries.

#### Supabase Data, Authentication, and Authorization
Supabase provides Postgres, Auth, Storage, and RLS-controlled API access. Client/server/admin connection boundaries are explicit in `lib/supabase/client.ts`, `lib/supabase/server.ts`, and `lib/supabase/admin.ts`; the latter is service-role-only and therefore reserved for verified server actions. Schema, seed data, database functions, roles, security logs, and storage policies evolve through `supabase/migrations/0001_init.sql` through `supabase/migrations/0010_fix_auth_audit_log_type.sql`. Email/password and Google OAuth flows are implemented in `features/auth/actions.ts` and return through `app/api/auth/callback/route.ts`.

#### Catalog and Cart Flow
Server-side catalog queries supply product lists, search, category pages, and PDPs through `features/catalog/queries.ts`, rendered by routes such as `app/(shop)/products/page.tsx`. The browser cart is a dedicated client-state boundary in `features/cart/store.ts`; interaction components such as `features/cart/add-to-cart-button.tsx` update it, while `app/cart/page.tsx` presents the current purchase state. Product imagery is served from local public assets and Supabase Storage, with admin uploads targeting the `product-images` bucket.

#### Checkout, Order Creation, and Payments
Checkout gathers validated customer/address input in `features/checkout/checkout-form.tsx` and invokes server-side orchestration in `features/checkout/actions.ts`. Razorpay server integration and payment-signature verification are isolated in `lib/razorpay/server.ts` and `lib/razorpay/verify.ts`. The normal browser verification path is supplemented by Razorpay’s authoritative asynchronous webhook at `app/api/razorpay/webhook/route.ts`; both paths update payment/order state and record relevant failures. Database-side order creation is established in `supabase/migrations/0003_create_order_function.sql`.

#### Administrative Operations
The admin area exposes metrics, order visibility, product creation/deletion, user deletion, and review moderation through `app/admin/page.tsx`, `app/admin/products/new/page.tsx`, and `features/admin/actions.ts`. Admin role originates in immutable-to-users `auth.users.app_metadata`, is checked from JWT claims, and is revalidated by server actions before service-role operations. Product creation accepts native `FormData`, validates uploaded file type/size server-side, writes product records, then uploads images; upload failure does not roll back the product.

#### Security and Developer Observability
Observed security events are logged by server code using `lib/security-log.ts`: failed authentication, failed checkout verification, and malformed/invalid Razorpay webhooks. Developer-only views in `app/developer/page.tsx` and `app/developer/auth-log/page.tsx` query event data and Supabase Auth audit records. The audit log crosses the otherwise protected `auth` schema through a security-definer database function introduced in `supabase/migrations/0008_developer_security_logs.sql`; it is not a client-exposed table.

Main entry points: [`app/(marketing)/page.tsx`](https://github.com/amalbabu0/ecomerce/blob/main/app/(marketing)/page.tsx) (Storefront routes), [`features/checkout/actions.ts`](https://github.com/amalbabu0/ecomerce/blob/main/features/checkout/actions.ts) (Checkout orchestration), [`lib/supabase/admin.ts`](https://github.com/amalbabu0/ecomerce/blob/main/lib/supabase/admin.ts) (Supabase connections), [`lib/security-log.ts`](https://github.com/amalbabu0/ecomerce/blob/main/lib/security-log.ts) (Security event log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js Web"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_access_proxy{{"Route access proxy<br/>Next.js proxy<br/>[proxy.ts]"}}
  node_storefront["Storefront routes<br/>App Router pages<br/>[page.tsx]"]
  node_catalog["Catalog queries<br/>server queries<br/>[queries.ts]"]
  node_cart_state["Browser cart<br/>client state<br/>[store.ts]"]
  node_checkout_actions["Checkout orchestration<br/>server actions<br/>[actions.ts]"]
  node_auth_actions["Auth flows<br/>server actions<br/>[actions.ts]"]
  node_auth_callback["OAuth callback<br/>API route<br/>[route.ts]"]
end

subgraph group_data["Supabase"]
  node_supabase_boundary{{"Supabase connections<br/>client/server/admin adapters<br/>[admin.ts]"}}
  node_supabase_platform[("Supabase platform<br/>Postgres, Auth, Storage, RLS")]
  node_schema_functions["Schema and DB functions<br/>SQL migrations"]
  node_product_storage[("Product images bucket<br/>Supabase Storage")]
end

subgraph group_payment["Payments"]
  node_razorpay_server["Razorpay server API<br/>payment integration<br/>[server.ts]"]
  node_payment_verify{{"Payment verification<br/>signature verification<br/>[verify.ts]"}}
  node_razorpay_webhook["Razorpay webhook<br/>API route<br/>[route.ts]"]
end

subgraph group_ops["Privileged Areas"]
  node_admin_area["Admin operations<br/>privileged routes<br/>[layout.tsx]"]
  node_admin_actions["Admin actions<br/>verified server actions<br/>[actions.ts]"]
  node_security_log["Security event log<br/>server logging<br/>[security-log.ts]"]
  node_developer_area["Developer observability<br/>privileged routes<br/>[page.tsx]"]
end

node_app_shell --> node_storefront
node_access_proxy -->|"mediates access"| node_storefront
node_access_proxy -->|"enforces route role"| node_admin_area
node_access_proxy -->|"enforces route role"| node_developer_area
node_storefront -->|"renders catalog"| node_catalog
node_storefront -->|"updates cart"| node_cart_state
node_storefront -->|"submits checkout"| node_checkout_actions
node_auth_actions -->|"OAuth return"| node_auth_callback
node_auth_actions -->|"uses auth adapter"| node_supabase_boundary
node_catalog -->|"server data access"| node_supabase_boundary
node_supabase_boundary -->|"accesses"| node_supabase_platform
node_schema_functions -->|"defines"| node_supabase_platform
node_checkout_actions -->|"creates payment"| node_razorpay_server
node_checkout_actions -->|"verifies browser result"| node_payment_verify
node_checkout_actions -->|"creates order"| node_schema_functions
node_payment_verify -->|"updates order state"| node_supabase_platform
node_razorpay_webhook -->|"authoritative state update"| node_supabase_platform
node_payment_verify -.->|"logs failures"| node_security_log
node_razorpay_webhook -.->|"logs invalid events"| node_security_log
node_admin_area -->|"invokes"| node_admin_actions
node_admin_actions -->|"verified service role"| node_supabase_boundary
node_admin_actions -->|"uploads images"| node_product_storage
node_security_log -->|"persists events"| node_supabase_platform
node_developer_area -->|"views events"| node_security_log
node_developer_area -->|"reads secure audit log"| node_schema_functions

click node_app_shell "https://github.com/amalbabu0/ecomerce/blob/main/app/layout.tsx"
click node_access_proxy "https://github.com/amalbabu0/ecomerce/blob/main/proxy.ts"
click node_storefront "https://github.com/amalbabu0/ecomerce/blob/main/app/(marketing)/page.tsx"
click node_catalog "https://github.com/amalbabu0/ecomerce/blob/main/features/catalog/queries.ts"
click node_cart_state "https://github.com/amalbabu0/ecomerce/blob/main/features/cart/store.ts"
click node_checkout_actions "https://github.com/amalbabu0/ecomerce/blob/main/features/checkout/actions.ts"
click node_auth_actions "https://github.com/amalbabu0/ecomerce/blob/main/features/auth/actions.ts"
click node_auth_callback "https://github.com/amalbabu0/ecomerce/blob/main/app/api/auth/callback/route.ts"
click node_supabase_boundary "https://github.com/amalbabu0/ecomerce/blob/main/lib/supabase/admin.ts"
click node_schema_functions "https://github.com/amalbabu0/ecomerce/blob/main/supabase/migrations/0003_create_order_function.sql"
click node_razorpay_server "https://github.com/amalbabu0/ecomerce/blob/main/lib/razorpay/server.ts"
click node_payment_verify "https://github.com/amalbabu0/ecomerce/blob/main/lib/razorpay/verify.ts"
click node_razorpay_webhook "https://github.com/amalbabu0/ecomerce/blob/main/app/api/razorpay/webhook/route.ts"
click node_admin_area "https://github.com/amalbabu0/ecomerce/blob/main/app/admin/layout.tsx"
click node_admin_actions "https://github.com/amalbabu0/ecomerce/blob/main/features/admin/actions.ts"
click node_security_log "https://github.com/amalbabu0/ecomerce/blob/main/lib/security-log.ts"
click node_developer_area "https://github.com/amalbabu0/ecomerce/blob/main/app/developer/auth-log/page.tsx"

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_shell,node_access_proxy,node_storefront,node_catalog,node_cart_state,node_checkout_actions,node_auth_actions,node_auth_callback toneBlue
class node_supabase_boundary,node_supabase_platform,node_schema_functions,node_product_storage toneAmber
class node_razorpay_server,node_payment_verify,node_razorpay_webhook toneMint
class node_admin_area,node_admin_actions,node_security_log,node_developer_area toneRose
```

## Components

### Next.js Web

App Router routes, proxy, and server-side features.

- [App shell](https://github.com/amalbabu0/ecomerce/blob/main/app/layout.tsx): Next.js layout · `app/layout.tsx`
- [Route access proxy](https://github.com/amalbabu0/ecomerce/blob/main/proxy.ts): Next.js proxy · Centralizes route access mediation. · `proxy.ts`
- [Storefront routes](https://github.com/amalbabu0/ecomerce/blob/main/app/(marketing)/page.tsx): App Router pages · Marketing, product discovery, cart, and checkout entry points. · `app/(marketing)/page.tsx`
- [Catalog queries](https://github.com/amalbabu0/ecomerce/blob/main/features/catalog/queries.ts): server queries · Supplies lists, search, categories, and product pages. · `features/catalog/queries.ts`
- [Browser cart](https://github.com/amalbabu0/ecomerce/blob/main/features/cart/store.ts): client state · Dedicated client-side purchase state. · `features/cart/store.ts`
- [Checkout orchestration](https://github.com/amalbabu0/ecomerce/blob/main/features/checkout/actions.ts): server actions · Validates checkout input and creates payment flow. · `features/checkout/actions.ts`
- [Auth flows](https://github.com/amalbabu0/ecomerce/blob/main/features/auth/actions.ts): server actions · Email/password and Google OAuth flows. · `features/auth/actions.ts`
- [OAuth callback](https://github.com/amalbabu0/ecomerce/blob/main/app/api/auth/callback/route.ts): API route · `app/api/auth/callback/route.ts`

### Supabase

Auth, Postgres, Storage, RLS, and database functions.

- [Supabase connections](https://github.com/amalbabu0/ecomerce/blob/main/lib/supabase/admin.ts): client/server/admin adapters · Service-role access is reserved for verified server operations. · `lib/supabase/admin.ts`
- **Supabase platform**: Postgres, Auth, Storage, RLS · Primary data, identity, storage, and policy boundary.
- [Schema and DB functions](https://github.com/amalbabu0/ecomerce/blob/main/supabase/migrations/0003_create_order_function.sql): SQL migrations · Defines policies, roles, order creation, and secure audit access. · `supabase/migrations/0003_create_order_function.sql`
- **Product images bucket**: Supabase Storage · Stores admin-uploaded product imagery.

### Payments

Checkout payment creation and verification.

- [Razorpay server API](https://github.com/amalbabu0/ecomerce/blob/main/lib/razorpay/server.ts): payment integration · Creates Razorpay payment operations server-side. · `lib/razorpay/server.ts`
- [Payment verification](https://github.com/amalbabu0/ecomerce/blob/main/lib/razorpay/verify.ts): signature verification · Verifies browser payment signatures. · `lib/razorpay/verify.ts`
- [Razorpay webhook](https://github.com/amalbabu0/ecomerce/blob/main/app/api/razorpay/webhook/route.ts): API route · Authoritative asynchronous payment updates. · `app/api/razorpay/webhook/route.ts`

### Privileged Areas

Role-protected administration and developer visibility.

- [Admin operations](https://github.com/amalbabu0/ecomerce/blob/main/app/admin/layout.tsx): privileged routes · Manages metrics, orders, products, users, and reviews. · `app/admin/layout.tsx`
- [Admin actions](https://github.com/amalbabu0/ecomerce/blob/main/features/admin/actions.ts): verified server actions · Revalidates admin role before service-role operations. · `features/admin/actions.ts`
- [Security event log](https://github.com/amalbabu0/ecomerce/blob/main/lib/security-log.ts): server logging · Records auth, checkout verification, and webhook failures. · `lib/security-log.ts`
- [Developer observability](https://github.com/amalbabu0/ecomerce/blob/main/app/developer/auth-log/page.tsx): privileged routes · Displays security events and Auth audit records. · `app/developer/auth-log/page.tsx`

## Connections

- App shell → Storefront routes
- Route access proxy → Storefront routes: mediates access
- Route access proxy → Admin operations: enforces route role
- Route access proxy → Developer observability: enforces route role
- Storefront routes → Catalog queries: renders catalog
- Storefront routes → Browser cart: updates cart
- Storefront routes → Checkout orchestration: submits checkout
- Auth flows → OAuth callback: OAuth return
- Auth flows → Supabase connections: uses auth adapter
- Catalog queries → Supabase connections: server data access
- Supabase connections → Supabase platform: accesses
- Schema and DB functions → Supabase platform: defines
- Checkout orchestration → Razorpay server API: creates payment
- Checkout orchestration → Payment verification: verifies browser result
- Checkout orchestration → Schema and DB functions: creates order
- Payment verification → Supabase platform: updates order state
- Razorpay webhook → Supabase platform: authoritative state update
- Payment verification → Security event log: logs failures
- Razorpay webhook → Security event log: logs invalid events
- Admin operations → Admin actions: invokes
- Admin actions → Supabase connections: verified service role
- Admin actions → Product images bucket: uploads images
- Security event log → Supabase platform: persists events
- Developer observability → Security event log: views events
- Developer observability → Schema and DB functions: reads secure audit log