# saranskumar/secondchances architecture

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

- Interactive diagram: https://gitdiagram.com/saranskumar/secondchances
- Repository: https://github.com/saranskumar/secondchances

## Overview

1. This is a Next.js App Router application that implements an e-commerce marketplace flow: public browsing, authenticated shopping, checkout, order management, and role-based dashboards for buyers and sellers.

2. The top-level architecture is split between UI routes under `src/app`, reusable UI/components under `src/components`, shared client state in `src/contexts`, and backend integration helpers in `src/lib/supabase`. The app appears to use Supabase as its primary backend for auth, database, and storage.

3. The route structure shows the main user journeys:
   - `src/app/page.tsx` as the landing/home page
   - `browse`, `products/[id]`, and `cart` for discovery and shopping
   - `checkout` for purchase completion
   - `orders/[id]` for order detail views
   - `dashboard/buyer` and `dashboard/seller` for role-specific account areas
   - `profile` for user profile/feedback
   - `auth/*` for sign-in, sign-up, OTP verification, password reset, and auth callback handling
   - `legal/*` for static policy pages

4. The data and business-logic boundary is centered in `src/actions`. These server-side action modules (`addresses.ts`, `orders.ts`, `products.ts`, `profile.ts`) likely encapsulate CRUD and workflow operations against Supabase, separating page/components from direct database access and keeping mutations on the server side.

5. Authentication is handled through Supabase helpers in `src/lib/supabase/client.ts`, `server.ts`, and `middleware.ts`, plus a global `src/middleware.ts`. This indicates a boundary where requests are authenticated/rewritten at the edge or server layer, while Supabase client instances are configured differently for browser, server, and middleware contexts.

6. The app uses a shared cart state in `src/contexts/CartContext.tsx`, which suggests cart interactions are client-side and persistent enough to be shared across browse/product/checkout pages. The Add to Cart button and product card components reinforce that product selection is a reusable front-end concern, with checkout likely consuming cart state rather than re-fetching it from every page.

7. UI composition is modular and layered:
   - `src/components/ui` contains primitive design-system controls such as `Button`, `Input`, `Card`, and `Badge`
   - `src/components/layout` contains cross-cutting shell elements like `Navbar` and `Footer`
   - `src/components/ProductCard` and `src/components/AddToCartButton` provide domain-specific commerce UI
   This suggests a clean separation between generic UI, layout chrome, and commerce-specific widgets.

8. The Supabase directory is an important infrastructure boundary. It contains schema, migrations, RLS policy material, and seed data:
   - `initial_schema.sql` and later migrations define the database structure
   - `storage_product_images.sql` indicates product image assets are stored in Supabase Storage
   - `addresses.sql` and order-related fixes show evolving relational data and access rules
   - `seed_mock_data.sql` supports local development/demo data
   This implies the app relies on database-enforced authorization, not just application-level checks.

9. The presence of `src/types/database.ts` suggests generated or hand-maintained typed database models used throughout the app to keep Supabase queries type-safe. In diagram terms, this is a shared contract layer between the Next.js app and the Supabase schema.

10. The runtime model is a hybrid Next.js setup: server components/pages and server actions for protected data access, client components for interactive shopping and form flows, and route handlers for auth callback processing. Middleware likely protects authenticated routes and/or refreshes Supabase sessions before requests reach pages.

11. The main data flow is:
   user lands on public pages → browses products fetched from Supabase → adds items to client cart state → checks out through server actions → order records are written to the database → authenticated users view orders/profile/dashboard data via server-rendered pages and actions. Auth flows are routed through Supabase and the `/auth/callback` handler.

12. Overall, the repo is best diagrammed as a Next.js front end layered over a Supabase backend, with clear separation between presentation, client state, server mutations, and database/storage/auth infrastructure.

Main entry points: [`src/lib/supabase/server.ts`](https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/server.ts) (Supabase server), [`src/actions/products.ts`](https://github.com/saranskumar/secondchances/blob/main/src/actions/products.ts) (Products actions), [`src/actions/orders.ts`](https://github.com/saranskumar/secondchances/blob/main/src/actions/orders.ts) (Orders actions), [`src/types/database.ts`](https://github.com/saranskumar/secondchances/blob/main/src/types/database.ts) (Database types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_src_app_page["Home<br/>route page<br/>[page.tsx]"]
  node_src_app_browse_page["Browse<br/>catalog route<br/>[page.tsx]"]
  node_src_app_products_id_page["Product detail<br/>product route<br/>[page.tsx]"]
  node_src_app_cart_page["Cart<br/>shopping route<br/>[page.tsx]"]
  node_src_app_checkout_page["Checkout<br/>order route<br/>[page.tsx]"]
  node_src_app_orders_id_page["Order detail<br/>order route<br/>[page.tsx]"]
  node_src_app_dashboard_buyer_page["Buyer dashboard<br/>account route<br/>[page.tsx]"]
  node_src_app_dashboard_seller_page["Seller dashboard<br/>account route<br/>[page.tsx]"]
  node_src_app_profile_page["Profile<br/>account route<br/>[page.tsx]"]
  node_src_app_auth_page["Auth hub<br/>auth route<br/>[page.tsx]"]
  node_src_app_auth_callback_route["Auth callback<br/>route handler<br/>[route.ts]"]
end

subgraph group_ui["UI layer"]
  node_src_components_layout_navbar["Navbar<br/>layout shell<br/>[Navbar.tsx]"]
  node_src_components_layout_footer["Footer<br/>layout shell<br/>[Footer.tsx]"]
  node_src_components_productcard["Product card<br/>commerce UI<br/>[ProductCard.tsx]"]
  node_src_components_addtocartbutton["Add to cart<br/>commerce UI"]
end

subgraph group_state["Client state"]
  node_src_contexts_cartcontext(("Cart state<br/>client context<br/>[CartContext.tsx]"))
end

subgraph group_server["Server logic"]
  node_src_actions_products["Products actions<br/>server actions<br/>[products.ts]"]
  node_src_actions_orders["Orders actions<br/>server actions<br/>[orders.ts]"]
  node_src_actions_addresses["Addresses actions<br/>server actions<br/>[addresses.ts]"]
  node_src_actions_profile["Profile actions<br/>server actions<br/>[profile.ts]"]
  node_src_lib_supabase_server["Supabase server<br/>backend client<br/>[server.ts]"]
  node_src_lib_supabase_client["Supabase browser<br/>backend client<br/>[client.ts]"]
  node_src_lib_supabase_middleware["Supabase middleware<br/>backend client<br/>[middleware.ts]"]
  node_src_middleware["App middleware<br/>edge middleware<br/>[middleware.ts]"]
end

subgraph group_infra["Supabase backend"]
  node_src_types_database["Database types<br/>typed contract<br/>[database.ts]"]
  node_supabase_schema[("Schema<br/>[schema.sql]")]
  node_supabase_migrations[("Migrations")]
  node_supabase_rls[("RLS policies<br/>db security<br/>[rls.sql]")]
  node_supabase_storage[("Image storage<br/>object storage")]
  node_supabase_seed["Seed data<br/>fixture data<br/>[seed_mock_data.sql]"]
end

node_src_app_page -->|"uses"| node_src_components_layout_navbar
node_src_app_page -->|"uses"| node_src_components_layout_footer
node_src_app_browse_page -->|"renders"| node_src_components_productcard
node_src_app_browse_page -->|"loads"| node_src_actions_products
node_src_app_products_id_page -->|"uses"| node_src_components_addtocartbutton
node_src_app_products_id_page -->|"loads"| node_src_actions_products
node_src_app_products_id_page -->|"updates"| node_src_contexts_cartcontext
node_src_app_cart_page -->|"consumes"| node_src_contexts_cartcontext
node_src_app_checkout_page -->|"consumes"| node_src_contexts_cartcontext
node_src_app_checkout_page -->|"submits"| node_src_actions_orders
node_src_app_checkout_page -->|"uses"| node_src_actions_addresses
node_src_app_orders_id_page -->|"loads"| node_src_actions_orders
node_src_app_dashboard_buyer_page -->|"loads"| node_src_actions_orders
node_src_app_dashboard_buyer_page -->|"loads"| node_src_actions_addresses
node_src_app_dashboard_seller_page -->|"loads"| node_src_actions_products
node_src_app_profile_page -->|"updates"| node_src_actions_profile
node_src_app_profile_page -->|"uses"| node_src_components_layout_navbar
node_src_app_auth_page -->|"authenticates"| node_src_lib_supabase_client
node_src_app_auth_callback_route -->|"finalizes"| node_src_lib_supabase_server
node_src_middleware -->|"wraps"| node_src_lib_supabase_middleware
node_src_actions_products -->|"queries"| node_src_lib_supabase_server
node_src_actions_orders -->|"queries"| node_src_lib_supabase_server
node_src_actions_addresses -->|"queries"| node_src_lib_supabase_server
node_src_actions_profile -->|"queries"| node_src_lib_supabase_server
node_src_lib_supabase_server -->|"typed by"| node_src_types_database
node_src_lib_supabase_client -->|"typed by"| node_src_types_database
node_src_lib_supabase_middleware -->|"typed by"| node_src_types_database
node_supabase_schema -->|"evolves into"| node_supabase_migrations
node_supabase_migrations -->|"enforces"| node_supabase_rls
node_supabase_migrations -->|"provisions"| node_supabase_storage
node_supabase_schema -->|"generates"| node_src_types_database
node_supabase_seed -->|"populates"| node_supabase_schema

click node_src_app_page "https://github.com/saranskumar/secondchances/blob/main/src/app/page.tsx"
click node_src_app_browse_page "https://github.com/saranskumar/secondchances/blob/main/src/app/browse/page.tsx"
click node_src_app_products_id_page "https://github.com/saranskumar/secondchances/blob/main/src/app/products/[id]/page.tsx"
click node_src_app_cart_page "https://github.com/saranskumar/secondchances/blob/main/src/app/cart/page.tsx"
click node_src_app_checkout_page "https://github.com/saranskumar/secondchances/blob/main/src/app/checkout/page.tsx"
click node_src_app_orders_id_page "https://github.com/saranskumar/secondchances/blob/main/src/app/orders/[id]/page.tsx"
click node_src_app_dashboard_buyer_page "https://github.com/saranskumar/secondchances/blob/main/src/app/dashboard/buyer/page.tsx"
click node_src_app_dashboard_seller_page "https://github.com/saranskumar/secondchances/blob/main/src/app/dashboard/seller/page.tsx"
click node_src_app_profile_page "https://github.com/saranskumar/secondchances/blob/main/src/app/profile/page.tsx"
click node_src_app_auth_page "https://github.com/saranskumar/secondchances/blob/main/src/app/auth/page.tsx"
click node_src_app_auth_callback_route "https://github.com/saranskumar/secondchances/blob/main/src/app/auth/callback/route.ts"
click node_src_components_layout_navbar "https://github.com/saranskumar/secondchances/blob/main/src/components/layout/Navbar.tsx"
click node_src_components_layout_footer "https://github.com/saranskumar/secondchances/blob/main/src/components/layout/Footer.tsx"
click node_src_components_productcard "https://github.com/saranskumar/secondchances/blob/main/src/components/ProductCard.tsx"
click node_src_components_addtocartbutton "https://github.com/saranskumar/secondchances/blob/main/src/components/AddToCartButton.tsx"
click node_src_contexts_cartcontext "https://github.com/saranskumar/secondchances/blob/main/src/contexts/CartContext.tsx"
click node_src_actions_products "https://github.com/saranskumar/secondchances/blob/main/src/actions/products.ts"
click node_src_actions_orders "https://github.com/saranskumar/secondchances/blob/main/src/actions/orders.ts"
click node_src_actions_addresses "https://github.com/saranskumar/secondchances/blob/main/src/actions/addresses.ts"
click node_src_actions_profile "https://github.com/saranskumar/secondchances/blob/main/src/actions/profile.ts"
click node_src_lib_supabase_server "https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/server.ts"
click node_src_lib_supabase_client "https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/client.ts"
click node_src_lib_supabase_middleware "https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/middleware.ts"
click node_src_middleware "https://github.com/saranskumar/secondchances/blob/main/src/middleware.ts"
click node_src_types_database "https://github.com/saranskumar/secondchances/blob/main/src/types/database.ts"
click node_supabase_schema "https://github.com/saranskumar/secondchances/blob/main/supabase/schema.sql"
click node_supabase_migrations "https://github.com/saranskumar/secondchances/blob/main/supabase/migrations/20260226000001_initial_schema.sql"
click node_supabase_rls "https://github.com/saranskumar/secondchances/blob/main/supabase/rls.sql"
click node_supabase_storage "https://github.com/saranskumar/secondchances/blob/main/supabase/migrations/20260313000002_storage_product_images.sql"
click node_supabase_seed "https://github.com/saranskumar/secondchances/blob/main/supabase/seed_mock_data.sql"

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_src_app_page,node_src_app_browse_page,node_src_app_products_id_page,node_src_app_cart_page,node_src_app_checkout_page,node_src_app_orders_id_page,node_src_app_dashboard_buyer_page,node_src_app_dashboard_seller_page,node_src_app_profile_page,node_src_app_auth_page,node_src_app_auth_callback_route toneBlue
class node_src_components_layout_navbar,node_src_components_layout_footer,node_src_components_productcard,node_src_components_addtocartbutton toneAmber
class node_src_contexts_cartcontext toneMint
class node_src_actions_products,node_src_actions_orders,node_src_actions_addresses,node_src_actions_profile,node_src_lib_supabase_server,node_src_lib_supabase_client,node_src_lib_supabase_middleware,node_src_middleware toneRose
class node_src_types_database,node_supabase_schema,node_supabase_migrations,node_supabase_rls,node_supabase_storage,node_supabase_seed toneIndigo
```

## Components

### Next.js app

Route segments and page flows

- [Home](https://github.com/saranskumar/secondchances/blob/main/src/app/page.tsx): route page · Landing page for public browsing · `src/app/page.tsx`
- [Browse](https://github.com/saranskumar/secondchances/blob/main/src/app/browse/page.tsx): catalog route · Product discovery and listing page · `src/app/browse/page.tsx`
- [Product detail](https://github.com/saranskumar/secondchances/blob/main/src/app/products/[id]/page.tsx): product route · Single product view and purchase entry · `src/app/products/[id]/page.tsx`
- [Cart](https://github.com/saranskumar/secondchances/blob/main/src/app/cart/page.tsx): shopping route · Client cart review and edits · `src/app/cart/page.tsx`
- [Checkout](https://github.com/saranskumar/secondchances/blob/main/src/app/checkout/page.tsx): order route · Purchase completion and payment flow · `src/app/checkout/page.tsx`
- [Order detail](https://github.com/saranskumar/secondchances/blob/main/src/app/orders/[id]/page.tsx): order route · View a specific order · `src/app/orders/[id]/page.tsx`
- [Buyer dashboard](https://github.com/saranskumar/secondchances/blob/main/src/app/dashboard/buyer/page.tsx): account route · Buyer order and account area · `src/app/dashboard/buyer/page.tsx`
- [Seller dashboard](https://github.com/saranskumar/secondchances/blob/main/src/app/dashboard/seller/page.tsx): account route · Seller inventory and marketplace area · `src/app/dashboard/seller/page.tsx`
- [Profile](https://github.com/saranskumar/secondchances/blob/main/src/app/profile/page.tsx): account route · User profile and feedback area · `src/app/profile/page.tsx`
- [Auth hub](https://github.com/saranskumar/secondchances/blob/main/src/app/auth/page.tsx): auth route · Entry page for authentication flows · `src/app/auth/page.tsx`
- [Auth callback](https://github.com/saranskumar/secondchances/blob/main/src/app/auth/callback/route.ts): route handler · Supabase auth callback processing · `src/app/auth/callback/route.ts`

### UI layer

Reusable presentation and layout components

- [Navbar](https://github.com/saranskumar/secondchances/blob/main/src/components/layout/Navbar.tsx): layout shell · Top-level navigation and session entry points · `src/components/layout/Navbar.tsx`
- [Footer](https://github.com/saranskumar/secondchances/blob/main/src/components/layout/Footer.tsx): layout shell · Shared bottom chrome · `src/components/layout/Footer.tsx`
- [Product card](https://github.com/saranskumar/secondchances/blob/main/src/components/ProductCard.tsx): commerce UI · Reusable product listing tile · `src/components/ProductCard.tsx`
- [Add to cart](https://github.com/saranskumar/secondchances/blob/main/src/components/AddToCartButton.tsx): commerce UI · Product purchase action button · `src/components/AddToCartButton.tsx`

### Client state

Shared browser-side state and context

- [Cart state](https://github.com/saranskumar/secondchances/blob/main/src/contexts/CartContext.tsx): client context · Shared cart state across shopping pages · `src/contexts/CartContext.tsx`

### Server logic

Server actions and request boundaries

- [Products actions](https://github.com/saranskumar/secondchances/blob/main/src/actions/products.ts): server actions · Server-side product reads and mutations · `src/actions/products.ts`
- [Orders actions](https://github.com/saranskumar/secondchances/blob/main/src/actions/orders.ts): server actions · Order creation and order workflow logic · `src/actions/orders.ts`
- [Addresses actions](https://github.com/saranskumar/secondchances/blob/main/src/actions/addresses.ts): server actions · Saved address CRUD for checkout and profile · `src/actions/addresses.ts`
- [Profile actions](https://github.com/saranskumar/secondchances/blob/main/src/actions/profile.ts): server actions · Profile and feedback updates · `src/actions/profile.ts`
- [Supabase server](https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/server.ts): backend client · Server-side Supabase client setup · `src/lib/supabase/server.ts`
- [Supabase browser](https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/client.ts): backend client · Client-side Supabase client setup · `src/lib/supabase/client.ts`
- [Supabase middleware](https://github.com/saranskumar/secondchances/blob/main/src/lib/supabase/middleware.ts): backend client · Auth/session handling for middleware · `src/lib/supabase/middleware.ts`
- [App middleware](https://github.com/saranskumar/secondchances/blob/main/src/middleware.ts): edge middleware · Global request interception and protection · `src/middleware.ts`

### Supabase backend

Auth, database, storage, and schema

- [Database types](https://github.com/saranskumar/secondchances/blob/main/src/types/database.ts): typed contract · Shared typed Supabase schema models · `src/types/database.ts`
- [Schema](https://github.com/saranskumar/secondchances/blob/main/supabase/schema.sql): db schema · Primary database structure definition · `supabase/schema.sql`
- [Migrations](https://github.com/saranskumar/secondchances/blob/main/supabase/migrations/20260226000001_initial_schema.sql): db migrations · Schema evolution and production upgrades · `supabase/migrations/20260226000001_initial_schema.sql`
- [RLS policies](https://github.com/saranskumar/secondchances/blob/main/supabase/rls.sql): db security · Row-level security rules and fixes · `supabase/rls.sql`
- [Image storage](https://github.com/saranskumar/secondchances/blob/main/supabase/migrations/20260313000002_storage_product_images.sql): object storage · Product image bucket and storage rules · `supabase/migrations/20260313000002_storage_product_images.sql`
- [Seed data](https://github.com/saranskumar/secondchances/blob/main/supabase/seed_mock_data.sql): fixture data · Mock and development seed data · `supabase/seed_mock_data.sql`

## Connections

- Home → Navbar: uses · Home page uses shared navigation
- Home → Footer: uses · Home page uses shared footer
- Browse → Product card: renders · Browse page shows product cards
- Browse → Products actions: loads · Fetches catalog data through server actions
- Product detail → Add to cart: uses · Product detail exposes add-to-cart action
- Product detail → Products actions: loads · Fetches product details from backend
- Product detail → Cart state: updates · Adds selected item to shared cart state
- Cart → Cart state: consumes · Cart page reads shared cart contents
- Checkout → Cart state: consumes · Checkout uses cart state as input
- Checkout → Orders actions: submits · Creates orders through server action
- Checkout → Addresses actions: uses · Uses saved addresses during checkout
- Order detail → Orders actions: loads · Fetches order detail and status
- Buyer dashboard → Orders actions: loads · Buyer dashboard summarizes orders
- Buyer dashboard → Addresses actions: loads · Buyer dashboard manages addresses
- Seller dashboard → Products actions: loads · Seller dashboard manages product listings
- Profile → Profile actions: updates · Profile page persists user changes
- Profile → Navbar: uses · Profile page uses shared navigation
- Auth hub → Supabase browser: authenticates · Auth flows run through browser Supabase client
- Auth callback → Supabase server: finalizes · Callback completes session exchange server-side
- App middleware → Supabase middleware: wraps · Global middleware delegates Supabase session handling
- Products actions → Supabase server: queries · Server actions access Supabase from the server
- Orders actions → Supabase server: queries · Order workflow uses server Supabase client
- Addresses actions → Supabase server: queries · Address CRUD uses server Supabase client
- Profile actions → Supabase server: queries · Profile mutations use server Supabase client
- Supabase server → Database types: typed by · Server queries use database types
- Supabase browser → Database types: typed by · Browser client uses database types
- Supabase middleware → Database types: typed by · Middleware client uses database types
- Schema → Migrations: evolves into · Schema is defined and updated by migrations
- Migrations → RLS policies: enforces · Migrations include security and access rules
- Migrations → Image storage: provisions · Storage setup for product images
- Schema → Database types: generates · Database schema backs shared typed models
- Seed data → Schema: populates · Seed data matches the schema
