# thomcray/fourthview-trading architecture

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

- Interactive diagram: https://gitdiagram.com/thomcray/fourthview-trading
- Repository: https://github.com/thomcray/fourthview-trading

## Overview

Fourthview Trading is a commerce and services platform: customers browse products or cars, manage a cart, pay, and track orders, alongside special orders, study applications, travel bookings, currency exchange, and account services. Administrators manage orders, catalogues, customers, refunds, applications, and settings. The graph groups related routes and UI into product areas; sampled handlers establish several backend calls, while unsampled route wiring is shown only at subsystem level. Supabase backs application data and uploads; Paystack and Resend provide payment and email integrations.

Main entry points: [`app/_lib/supabase-server.ts`](https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/supabase-server.ts) (Supabase Data), [`app/api/study-applications/route.ts`](https://github.com/thomcray/fourthview-trading/blob/main/app/api/study-applications/route.ts) (Study Application Routes), [`app/api/exchange-transactions/route.ts`](https://github.com/thomcray/fourthview-trading/blob/main/app/api/exchange-transactions/route.ts) (Exchange Routes), [`app/(site)/cart`](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/cart) (Cart and Checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront Commerce"]
  node_storefront_ui["Shop and Catalog"]
  node_product_ui["Product and Car Views"]
  node_cart_ui["Cart and Checkout"]
  node_commerce_api["Commerce Routes"]
  node_orders_ui["Orders and Status"]
  node_payment_api["Payment Routes"]
  node_paystack_hook["Paystack Webhook<br/>[route.ts]"]
  node_cars_ui["Car Marketplace"]
  node_reviews_api["Product and Car Reviews<br/>[route.ts]"]
end

subgraph group_operations["Admin Operations"]
  node_admin_ui["Admin Console"]
  node_admin_api["Admin Routes"]
end

subgraph group_services["Customer Services"]
  node_special_orders["Special Orders"]
  node_study_ui["Study Applications"]
  node_study_api["Study Application Routes<br/>[route.ts]"]
  node_study_upload["Study Document Upload<br/>[route.ts]"]
  node_travel_ui["Travel and Bookings"]
  node_exchange_ui["Currency Exchange<br/>[MoneySection.tsx]"]
  node_exchange_api["Exchange Routes<br/>[route.ts]"]
  node_exchange_rates["Rates and Settings<br/>[route.ts]"]
end

subgraph group_platform["Platform Services"]
  node_auth_api["Authentication and Signup<br/>[route.ts]"]
  node_supabase[("Supabase Data<br/>[supabase-server.ts]")]
  node_supabase_storage[("Supabase Storage<br/>[supabase-server.ts]")]
  node_notifications["Notifications and Email"]
end

node_customer(("Customer"))
node_paystack{{"Paystack"}}
node_resend{{"Resend Email"}}
node_exchange_provider{{"Exchange Rate API"}}

node_customer -->|"browses"| node_storefront_ui
node_customer -->|"browses"| node_cars_ui
node_customer -->|"manages cart"| node_cart_ui
node_customer -->|"applies"| node_study_ui
node_customer -->|"books services"| node_travel_ui
node_customer -->|"exchanges currency"| node_exchange_ui
node_storefront_ui -->|"opens products"| node_product_ui
node_cart_ui -->|"updates cart"| node_commerce_api
node_cart_ui -->|"starts payment"| node_payment_api
node_payment_api -->|"initiates payment"| node_paystack
node_paystack -->|"sends event"| node_paystack_hook
node_paystack_hook -->|"records order"| node_supabase
node_paystack_hook -->|"notifies"| node_notifications
node_notifications -.->|"sends email"| node_resend
node_orders_ui -->|"requests orders"| node_commerce_api
node_customer -->|"submits review"| node_reviews_api
node_reviews_api -->|"reads and writes"| node_supabase
node_admin_ui -->|"manages records"| node_admin_api
node_admin_api -->|"reads and writes"| node_supabase
node_customer -->|"signs up"| node_auth_api
node_auth_api -->|"stores pending user"| node_supabase
node_auth_api -->|"sends verification"| node_resend
node_customer -->|"submits application"| node_study_api
node_study_api -->|"stores application"| node_supabase
node_study_api -->|"notifies admins"| node_notifications
node_study_api -.->|"sends application email"| node_resend
node_study_api -->|"loads settings"| node_supabase
node_customer -->|"requests upload"| node_study_upload
node_study_upload -->|"checks ownership"| node_supabase
node_study_upload -->|"creates signed upload"| node_supabase_storage
node_exchange_ui -->|"submits transaction"| node_exchange_api
node_exchange_api -->|"uploads receipt"| node_supabase_storage
node_exchange_api -->|"stores transaction"| node_supabase
node_exchange_rates -->|"reads and caches rates"| node_supabase
node_exchange_rates -.->|"fetches rates"| node_exchange_provider
node_exchange_api -->|"reads transactions"| node_supabase
node_exchange_ui -->|"requests rates"| node_exchange_rates
node_special_orders -->|"stores requests"| node_supabase
node_travel_ui -->|"requests service"| node_special_orders

click node_storefront_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/shop"
click node_product_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/item-description"
click node_cart_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/cart"
click node_commerce_api "https://github.com/thomcray/fourthview-trading/tree/main/app/api/cart"
click node_orders_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/orders"
click node_payment_api "https://github.com/thomcray/fourthview-trading/tree/main/app/api/payment"
click node_paystack_hook "https://github.com/thomcray/fourthview-trading/blob/main/app/api/webhooks/paystack/route.ts"
click node_cars_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/car"
click node_reviews_api "https://github.com/thomcray/fourthview-trading/blob/main/app/api/product-reviews/route.ts"
click node_admin_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/admin"
click node_admin_api "https://github.com/thomcray/fourthview-trading/tree/main/app/api/admin"
click node_special_orders "https://github.com/thomcray/fourthview-trading/tree/main/app/api/special-orders"
click node_study_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/study-in-china"
click node_study_api "https://github.com/thomcray/fourthview-trading/blob/main/app/api/study-applications/route.ts"
click node_study_upload "https://github.com/thomcray/fourthview-trading/blob/main/app/api/study-document/route.ts"
click node_travel_ui "https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/travel"
click node_exchange_ui "https://github.com/thomcray/fourthview-trading/blob/main/components/MoneySection/MoneySection.tsx"
click node_exchange_api "https://github.com/thomcray/fourthview-trading/blob/main/app/api/exchange-transactions/route.ts"
click node_exchange_rates "https://github.com/thomcray/fourthview-trading/blob/main/app/api/exchange-rate/route.ts"
click node_auth_api "https://github.com/thomcray/fourthview-trading/blob/main/app/api/send/route.ts"
click node_supabase "https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/supabase-server.ts"
click node_supabase_storage "https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/supabase-server.ts"
click node_notifications "https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/create-notification.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_storefront_ui,node_product_ui,node_cart_ui,node_commerce_api,node_orders_ui,node_payment_api,node_paystack_hook,node_cars_ui,node_reviews_api toneBlue
class node_admin_ui,node_admin_api toneAmber
class node_special_orders,node_study_ui,node_study_api,node_study_upload,node_travel_ui,node_exchange_ui,node_exchange_api,node_exchange_rates,node_exchange_provider toneMint
class node_auth_api,node_supabase,node_supabase_storage,node_notifications toneRose
class node_customer,node_paystack,node_resend toneIndigo
```

## Components

### Storefront Commerce

- [Shop and Catalog](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/shop): `app/(site)/shop`
- [Product and Car Views](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/item-description): `app/(site)/item-description`
- [Cart and Checkout](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/cart): `app/(site)/cart`
- [Commerce Routes](https://github.com/thomcray/fourthview-trading/tree/main/app/api/cart): `app/api/cart`
- [Orders and Status](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/orders): `app/(site)/orders`
- [Payment Routes](https://github.com/thomcray/fourthview-trading/tree/main/app/api/payment): `app/api/payment`
- [Paystack Webhook](https://github.com/thomcray/fourthview-trading/blob/main/app/api/webhooks/paystack/route.ts): `app/api/webhooks/paystack/route.ts`
- [Car Marketplace](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/car): `app/(site)/car`
- [Product and Car Reviews](https://github.com/thomcray/fourthview-trading/blob/main/app/api/product-reviews/route.ts): `app/api/product-reviews/route.ts`

### Admin Operations

- [Admin Console](https://github.com/thomcray/fourthview-trading/tree/main/app/admin): `app/admin`
- [Admin Routes](https://github.com/thomcray/fourthview-trading/tree/main/app/api/admin): `app/api/admin`

### Customer Services

- [Special Orders](https://github.com/thomcray/fourthview-trading/tree/main/app/api/special-orders): `app/api/special-orders`
- [Study Applications](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/study-in-china): `app/(site)/study-in-china`
- [Study Application Routes](https://github.com/thomcray/fourthview-trading/blob/main/app/api/study-applications/route.ts): `app/api/study-applications/route.ts`
- [Study Document Upload](https://github.com/thomcray/fourthview-trading/blob/main/app/api/study-document/route.ts): `app/api/study-document/route.ts`
- [Travel and Bookings](https://github.com/thomcray/fourthview-trading/tree/main/app/(site)/travel): `app/(site)/travel`
- [Currency Exchange](https://github.com/thomcray/fourthview-trading/blob/main/components/MoneySection/MoneySection.tsx): `components/MoneySection/MoneySection.tsx`
- [Exchange Routes](https://github.com/thomcray/fourthview-trading/blob/main/app/api/exchange-transactions/route.ts): `app/api/exchange-transactions/route.ts`
- [Rates and Settings](https://github.com/thomcray/fourthview-trading/blob/main/app/api/exchange-rate/route.ts): `app/api/exchange-rate/route.ts`

### Platform Services

- [Authentication and Signup](https://github.com/thomcray/fourthview-trading/blob/main/app/api/send/route.ts): `app/api/send/route.ts`
- [Supabase Data](https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/supabase-server.ts): `app/_lib/supabase-server.ts`
- [Supabase Storage](https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/supabase-server.ts): `app/_lib/supabase-server.ts`
- [Notifications and Email](https://github.com/thomcray/fourthview-trading/blob/main/app/_lib/create-notification.ts): `app/_lib/create-notification.ts`

### Other components

- **Customer**
- **Paystack**
- **Resend Email**
- **Exchange Rate API**

## Connections

- Customer → Shop and Catalog: browses
- Customer → Car Marketplace: browses
- Customer → Cart and Checkout: manages cart
- Customer → Study Applications: applies
- Customer → Travel and Bookings: books services
- Customer → Currency Exchange: exchanges currency
- Shop and Catalog → Product and Car Views: opens products
- Cart and Checkout → Commerce Routes: updates cart
- Cart and Checkout → Payment Routes: starts payment
- Payment Routes → Paystack: initiates payment
- Paystack → Paystack Webhook: sends event
- Paystack Webhook → Supabase Data: records order
- Paystack Webhook → Notifications and Email: notifies
- Notifications and Email → Resend Email: sends email
- Orders and Status → Commerce Routes: requests orders
- Customer → Product and Car Reviews: submits review
- Product and Car Reviews → Supabase Data: reads and writes
- Admin Console → Admin Routes: manages records
- Admin Routes → Supabase Data: reads and writes
- Customer → Authentication and Signup: signs up
- Authentication and Signup → Supabase Data: stores pending user
- Authentication and Signup → Resend Email: sends verification
- Customer → Study Application Routes: submits application
- Study Application Routes → Supabase Data: stores application
- Study Application Routes → Notifications and Email: notifies admins
- Study Application Routes → Resend Email: sends application email
- Study Application Routes → Supabase Data: loads settings
- Customer → Study Document Upload: requests upload
- Study Document Upload → Supabase Data: checks ownership
- Study Document Upload → Supabase Storage: creates signed upload
- Currency Exchange → Exchange Routes: submits transaction
- Exchange Routes → Supabase Storage: uploads receipt
- Exchange Routes → Supabase Data: stores transaction
- Rates and Settings → Supabase Data: reads and caches rates
- Rates and Settings → Exchange Rate API: fetches rates
- Exchange Routes → Supabase Data: reads transactions
- Currency Exchange → Rates and Settings: requests rates
- Special Orders → Supabase Data: stores requests
- Travel and Bookings → Special Orders: requests service