# venomous-pie/knot-and-bloom architecture

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

- Interactive diagram: https://gitdiagram.com/venomous-pie/knot-and-bloom
- Repository: https://github.com/venomous-pie/knot-and-bloom

## Overview

Knot & Bloom is a curated marketplace connecting buyers with verified Filipino makers. Buyers discover products, place deposit-backed orders, and track fulfillment; sellers onboard and manage listings and orders, while admins curate products and resolve disputes. The graph separates the customer-facing app, API entry and domain handlers, marketplace services, and persistence. Source excerpts show product routing, checkout dependencies, and review routing; other capability links reflect the README or are left unconnected where implementation wiring was not sampled.

Main entry points: [`backend/src/index.ts`](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/index.ts) (HTTP API), [`backend/src/controllers/CheckoutController.ts`](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/CheckoutController.ts) (Checkout and orders), [`backend/src/utils/prismaUtils.ts`](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/prismaUtils.ts) (Database client), [`backend/src/routes/productRoutes.ts`](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/routes/productRoutes.ts) (Product routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Marketplace app"]
  node_buyer_app["Buyer experience"]
  node_seller_app["Seller workspace"]
  node_admin_app["Admin workspace"]
end

subgraph group_api["API and domain handlers"]
  node_api_entry["HTTP API<br/>[index.ts]"]
  node_product_routes["Product routes<br/>[productRoutes.ts]"]
  node_product_domain["Catalog management"]
  node_checkout_domain["Checkout and orders"]
  node_review_routes["Review routes<br/>[reviewRoutes.ts]"]
  node_review_domain["Reviews"]
  node_account_domain["Accounts"]
  node_seller_domain["Seller onboarding"]
  node_dispute_domain["Disputes"]
  node_auth["Authentication<br/>[authMiddleware.ts]"]
end

subgraph group_services["Marketplace services"]
  node_listing_assist["Listing assistance<br/>[GenerateService.ts]"]
  node_payment["Payment handling<br/>[PaymentService.ts]"]
  node_pricing["Pricing and fees<br/>[pricingUtils.ts]"]
  node_shipping["Shipping configuration"]
  node_audit["Audit records<br/>[AuditService.ts]"]
  node_scheduled["Scheduled operations<br/>[cronService.ts]"]
  node_media["Media storage<br/>[SupabaseService.ts]"]
end

subgraph group_data["Persistence"]
  node_db_client["Database client<br/>[prismaUtils.ts]"]
  node_database[("Marketplace database")]
end

node_buyers(("Buyers"))
node_sellers(("Makers"))
node_admins(("Marketplace admins"))

node_buyers -.->|"browse and buy"| node_buyer_app
node_sellers -.->|"manage storefront"| node_seller_app
node_admins -.->|"curate and resolve"| node_admin_app
node_buyer_app -.->|"requests"| node_api_entry
node_seller_app -.->|"requests"| node_api_entry
node_admin_app -.->|"requests"| node_api_entry
node_api_entry -->|"mounts routes"| node_product_routes
node_product_routes -->|"dispatches catalog"| node_product_domain
node_product_routes -->|"generates listing data"| node_listing_assist
node_product_domain -->|"queries catalog"| node_db_client
node_api_entry -->|"mounts routes"| node_checkout_domain
node_checkout_domain -->|"initiates payment"| node_payment
node_checkout_domain -->|"calculates charges"| node_pricing
node_checkout_domain -->|"loads configuration"| node_shipping
node_checkout_domain -->|"persists orders"| node_db_client
node_api_entry -->|"mounts routes"| node_review_routes
node_review_routes -->|"dispatches reviews"| node_review_domain
node_review_domain -->|"queries reviews"| node_db_client
node_api_entry -->|"mounts routes"| node_seller_domain
node_api_entry -->|"mounts routes"| node_account_domain
node_api_entry -->|"mounts admin routes"| node_dispute_domain
node_api_entry -->|"applies authentication"| node_auth
node_auth -.->|"uses auth claims"| node_db_client
node_db_client -.->|"reads and writes"| node_database

click node_buyer_app "https://github.com/venomous-pie/knot-and-bloom/tree/master/frontend/app"
click node_seller_app "https://github.com/venomous-pie/knot-and-bloom/tree/master/frontend/app/seller-dashboard"
click node_admin_app "https://github.com/venomous-pie/knot-and-bloom/tree/master/frontend/app/admin"
click node_api_entry "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/index.ts"
click node_product_routes "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/routes/productRoutes.ts"
click node_product_domain "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/ProductController.ts"
click node_checkout_domain "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/CheckoutController.ts"
click node_review_routes "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/routes/reviewRoutes.ts"
click node_review_domain "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/ReviewController.ts"
click node_account_domain "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/AccountController.ts"
click node_seller_domain "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/SellerController.ts"
click node_dispute_domain "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/DisputeController.ts"
click node_auth "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/middleware/authMiddleware.ts"
click node_listing_assist "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/GenerateService.ts"
click node_payment "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/PaymentService.ts"
click node_pricing "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/pricingUtils.ts"
click node_shipping "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/platformConfigUtils.ts"
click node_audit "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/AuditService.ts"
click node_scheduled "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/cronService.ts"
click node_media "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/SupabaseService.ts"
click node_db_client "https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/prismaUtils.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_buyer_app,node_seller_app,node_admin_app toneBlue
class node_api_entry,node_product_routes,node_product_domain,node_checkout_domain,node_review_routes,node_review_domain,node_account_domain,node_seller_domain,node_dispute_domain,node_auth toneAmber
class node_listing_assist,node_payment,node_pricing,node_shipping,node_audit,node_scheduled,node_media toneMint
class node_db_client,node_database toneRose
class node_buyers,node_sellers,node_admins toneIndigo
```

## Components

### Marketplace app

- [Buyer experience](https://github.com/venomous-pie/knot-and-bloom/tree/master/frontend/app): `frontend/app`
- [Seller workspace](https://github.com/venomous-pie/knot-and-bloom/tree/master/frontend/app/seller-dashboard): `frontend/app/seller-dashboard`
- [Admin workspace](https://github.com/venomous-pie/knot-and-bloom/tree/master/frontend/app/admin): `frontend/app/admin`

### API and domain handlers

- [HTTP API](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/index.ts): `backend/src/index.ts`
- [Product routes](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/routes/productRoutes.ts): `backend/src/routes/productRoutes.ts`
- [Catalog management](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/ProductController.ts): `backend/src/controllers/ProductController.ts`
- [Checkout and orders](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/CheckoutController.ts): `backend/src/controllers/CheckoutController.ts`
- [Review routes](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/routes/reviewRoutes.ts): `backend/src/routes/reviewRoutes.ts`
- [Reviews](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/ReviewController.ts): `backend/src/controllers/ReviewController.ts`
- [Accounts](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/AccountController.ts): `backend/src/controllers/AccountController.ts`
- [Seller onboarding](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/SellerController.ts): `backend/src/controllers/SellerController.ts`
- [Disputes](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/controllers/DisputeController.ts): `backend/src/controllers/DisputeController.ts`
- [Authentication](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/middleware/authMiddleware.ts): `backend/src/middleware/authMiddleware.ts`

### Marketplace services

- [Listing assistance](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/GenerateService.ts): `backend/src/services/GenerateService.ts`
- [Payment handling](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/PaymentService.ts): `backend/src/services/PaymentService.ts`
- [Pricing and fees](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/pricingUtils.ts): `backend/src/utils/pricingUtils.ts`
- [Shipping configuration](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/platformConfigUtils.ts): `backend/src/utils/platformConfigUtils.ts`
- [Audit records](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/AuditService.ts): `backend/src/services/AuditService.ts`
- [Scheduled operations](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/cronService.ts): `backend/src/services/cronService.ts`
- [Media storage](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/services/SupabaseService.ts): `backend/src/services/SupabaseService.ts`

### Persistence

- [Database client](https://github.com/venomous-pie/knot-and-bloom/blob/master/backend/src/utils/prismaUtils.ts): `backend/src/utils/prismaUtils.ts`
- **Marketplace database**

### Other components

- **Buyers**
- **Makers**
- **Marketplace admins**

## Connections

- Buyers → Buyer experience: browse and buy (evidence: `README.md`)
- Makers → Seller workspace: manage storefront (evidence: `README.md`)
- Marketplace admins → Admin workspace: curate and resolve (evidence: `README.md`)
- Buyer experience → HTTP API: requests
- Seller workspace → HTTP API: requests
- Admin workspace → HTTP API: requests
- HTTP API → Product routes: mounts routes (evidence: `backend/src/index.ts`)
- Product routes → Catalog management: dispatches catalog (evidence: `backend/src/routes/productRoutes.ts`)
- Product routes → Listing assistance: generates listing data (evidence: `backend/src/routes/productRoutes.ts`)
- Catalog management → Database client: queries catalog (evidence: `backend/src/controllers/ProductController.ts`)
- HTTP API → Checkout and orders: mounts routes (evidence: `backend/src/index.ts`)
- Checkout and orders → Payment handling: initiates payment (evidence: `backend/src/controllers/CheckoutController.ts`)
- Checkout and orders → Pricing and fees: calculates charges (evidence: `backend/src/controllers/CheckoutController.ts`)
- Checkout and orders → Shipping configuration: loads configuration (evidence: `backend/src/controllers/CheckoutController.ts`)
- Checkout and orders → Database client: persists orders (evidence: `backend/src/controllers/CheckoutController.ts`)
- HTTP API → Review routes: mounts routes (evidence: `backend/src/index.ts`)
- Review routes → Reviews: dispatches reviews (evidence: `backend/src/routes/reviewRoutes.ts`)
- Reviews → Database client: queries reviews (evidence: `backend/src/controllers/ReviewController.ts`)
- HTTP API → Seller onboarding: mounts routes (evidence: `backend/src/index.ts`)
- HTTP API → Accounts: mounts routes (evidence: `backend/src/index.ts`)
- HTTP API → Disputes: mounts admin routes (evidence: `backend/src/index.ts`)
- HTTP API → Authentication: applies authentication (evidence: `backend/src/index.ts`)
- Authentication → Database client: uses auth claims
- Database client → Marketplace database: reads and writes
