Bellingham 3D Backend is a KeystoneJS-based ecommerce backend for the Bellingham 3D store that exposes a GraphQL API and a Next.js admin UI for managing products, orders, and secure checkout.
What is Bellingham 3D Backend?
This is a full-stack ecommerce backend written in TypeScript that uses KeystoneJS as its core. KeystoneJS is a Node.js and TypeScript GraphQL server-side client that uses Next.js for the admin UI. The backend automatically generates basic GraphQL resolvers through Prisma and connects to a PostgreSQL database to expose a GraphQL API endpoint. It also includes custom resolvers in a mutations folder for advanced logic, such as the Stripe checkout mutation. The project is hosted on a Digital Ocean droplet and uses Supabase for PostgreSQL hosting in production.
Key Features
- KeystoneJS with Next.js admin UI — The admin UI acts as a CMS for performing CRUD operations on database items, all built with Next.js and TypeScript.
- Prisma-generated GraphQL resolvers — Keystone generates basic resolvers using Prisma, reducing boilerplate for standard data access.
- Server-side Stripe checkout — The final checkout mutation is handled on the server, where prices are recalculated with product information from the database to ensure correct charges.
- Order creation and storage — Completed carts are converted into orders, saved to the database, and an order confirmation is returned to the client.
- PostgreSQL on Supabase — Production data is stored in a PostgreSQL database hosted on Supabase.
- Custom mutations folder — More advanced resolvers beyond the generated ones are organized in a dedicated mutations folder.
- Environment-based configuration — Setup requires Cloudinary, Stripe, and SMTP credentials in a .env file, with an .env.sample provided for reference.
Who is it for?
- Ecommerce developers — Anyone building a storefront backend who wants a functional reference for integrating KeystoneJS with GraphQL, Prisma, and Stripe.
- Store owners with custom needs — Teams that need a customizable admin CMS to manage products, orders, and other store data without relying on a SaaS platform.
- Stripe-based projects — Developers who require a checkout flow where pricing is verified server-side to prevent tampering.
- Full-stack learners — People studying TypeScript, GraphQL, Prisma, and Next.js who want a real-world example of a production-style backend.
What can you do with it?
- Run the backend locally — Clone the repository, run
npm installoryarn, thennpm run devoryarn dev; the GraphQL server and admin UI start on localhost:3000. - Connect a frontend client — Use the separate bellingham3d-frontend repository (https://github.com/ryan3738/bellingham3d-frontend) to build a storefront that consumes this GraphQL API.
- Manage store data — Use the admin UI as a CMS to add, edit, or remove products and other database items.
- Implement secure checkout — Rely on the server-side Stripe mutation to recalculate order totals from database prices before charging the customer.
How does the checkout work?
The checkout mutation is executed entirely on the server. First, the mutation receives the cart from the client. Then, the server recalculates prices using product information from the database to ensure accurate amounts. After that, the cart is converted into an order and saved to the database. Finally, an order object with purchase details is returned to the client.
FAQ
What credentials are required to run this project?
You need Cloudinary, Stripe, and SMTP credentials set in your .env file or environment variables. The repository includes an .env.sample file that lists the required fields.
How do I start the development server?
Clone the repository, install dependencies with npm or yarn, and run npm run dev or yarn dev. The GraphQL server and admin UI will be available at localhost:3000.
What database does this backend use?
The backend uses PostgreSQL. In production, the database is hosted on Supabase, and the deployment runs on a Digital Ocean droplet.
Is the frontend included in this repository?
No. The frontend client is a separate project. The README links to the bellingham3d-frontend repository at https://github.com/ryan3738/bellingham3d-frontend.
Which Node package managers are supported?
Both npm and yarn are supported. The README shows npm install / npm run dev and yarn / yarn dev as equivalent alternatives.
