POST
/api/stripe/checkoutCreate a Stripe Checkout session
Accepts
{ priceId, mode?, successUrl?, cancelUrl? }
Returns
{ url: string }
Engineering Reference
Architecture & Tech Stack: How This Project Works
This document describes the technical architecture of the Pinehaven Ventures website: the stack, deployment pipeline, manifest-driven code generation, file map, component inventory, API routes, and environment variables.
Last updated: March 3, 2026. Reflects the current production architecture on pinehavenventures.io.
Tech stack
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Framework | Next.js | 16.x | App Router, server components, API routes, static/dynamic rendering |
| UI Library | React | 19.x | Component model, hooks, server/client component split |
| Language | TypeScript | 5.x | Type safety across all source files, strict mode enabled |
| Styling | Tailwind CSS | 4.x | Utility-first CSS via PostCSS plugin, theme variables in globals.css |
| Payments | Stripe SDK | 20.x (server) / 8.x (client) | Hosted Checkout, subscriptions, billing portal, webhooks |
| Hosting | Vercel | Managed | Automatic deployments from GitHub, edge network, environment variables |
| Script Runner | tsx | 4.x | Executes TypeScript scripts (generator, seed) without a compile step |
| Linting | ESLint | 9.x | Code quality with next/core-web-vitals and next/typescript configs |
Deployment pipeline
Code flows from a single JSON manifest to a live production site in six steps. Vercel handles build and hosting automatically on every push.
1
Edit ventures.json
All product, plan, and pricing changes start here. This is the single source of truth.
2
Run npm run generate
Reads ventures.json and regenerates stripe-products.ts, seed-stripe.ts, .env.example, and scaffolds new product pages.
3
Customize generated pages
Product pages are scaffolded once and never overwritten. Enhance hero copy, features, and layout after generation.
4
Verify locally
Run npx tsc --noEmit (type check) and npm run build (full production build) to catch errors before pushing.
5
Push to GitHub
Commit changes and push to the repository. Vercel watches the repo for changes.
6
Vercel builds and deploys
Vercel automatically runs next build and deploys to pinehavenventures.io. Environment variables are configured in Vercel dashboard.
Manifest-driven code generation
ventures.json in the project root is the single source of truth. Every product, plan, price, and feature is defined there. The generator script reads this file and produces all derived code, eliminating manual synchronization across Stripe configs, environment variables, and page scaffolds.
What the generator produces
src/lib/stripe-products.tsRuntime Stripe product configuration with helper functions (getProductBySlug, getPlanById, formatPrice).
scripts/seed-stripe.tsScript to provision Stripe products/prices and configure the billing portal.
.env.exampleEnvironment variable template with placeholders for all Stripe price IDs.
src/app/ventures/<id>/page.tsxProduct page scaffold (only created for new ventures, never overwrites existing pages).
File map
Files marked as generated are overwritten by npm run generate. Do not edit them manually.
| Path | Generated? | Purpose |
|---|---|---|
| ventures.json | Manual | Single source of truth for all ventures, plans, and pricing |
| scripts/generate-from-manifest.ts | Manual | Generator script that reads ventures.json and produces generated files |
| scripts/seed-stripe.ts | Generated | Stripe product/price provisioning and billing portal setup |
| src/lib/stripe-products.ts | Generated | Runtime Stripe config with product lookup helpers |
| src/lib/stripe.ts | Manual | Server-side Stripe client initialization |
| src/lib/stripe-client.ts | Manual | Client-side loadStripe wrapper |
| .env.example | Generated | Environment variable template |
| src/app/ventures/*/page.tsx | Manual | Product pages (scaffolded once, then customized) |
| src/app/api/stripe/*/route.ts | Manual | Generic API routes (checkout, webhooks, portal) |
| src/app/components/*.tsx | Manual | Shared UI components |
| src/app/reference/*/page.tsx | Manual | Toolkit reference documents |
| src/app/toolkit/page.tsx | Manual | Toolkit hub page listing all reference docs |
| src/app/checkout/*/page.tsx | Manual | Post-checkout success and cancel pages |
Component inventory
All shared components live in src/app/components/. Every component is a client component (marked with 'use client').
| Component | Props | Used in |
|---|---|---|
Navigationsrc/app/components/Navigation.tsx | None | Every page (layout-level) |
CheckoutButtonsrc/app/components/CheckoutButton.tsx | priceId, mode, label, className | PricingCard, product pages |
PricingCardsrc/app/components/PricingCard.tsx | name, price, interval, priceId, features, highlighted, badge | All product pages with paid plans |
LeadCapturesrc/app/components/LeadCapture.tsx | None | Homepage |
ContactFormsrc/app/components/ContactForm.tsx | None | Homepage (#contact anchor) |
SubscribeBannersrc/app/components/SubscribeBanner.tsx | None | Power Queue Tracker product page |
API routes
All API routes are generic and accept any valid input. No changes are needed when adding new products.
POST
/api/stripe/webhooksReceive and process Stripe webhook events
Accepts
Raw body with stripe-signature header
Returns
{ received: true }
POST
/api/stripe/portalCreate a billing portal session
Accepts
{ customerId }
Returns
{ url: string }
POST
/api/subscribeCapture email signups (Airtable integration)
Accepts
{ email, source }
Returns
{ success: true }
Environment variables
Variables go in .env.local (gitignored). Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Generated variables are auto-populated by npm run generate into .env.example.
| Variable | Scope | Description | Source |
|---|---|---|---|
| STRIPE_SECRET_KEY | server | Server-side Stripe API key | Manual |
| NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | client | Client-side Stripe publishable key | Manual |
| STRIPE_WEBHOOK_SECRET | server | Webhook signing secret from Stripe Dashboard | Manual |
| NEXT_PUBLIC_APP_URL | client | Base URL for checkout redirects | Manual |
| AIRTABLE_TOKEN | server | Airtable API token for lead capture | Manual |
| AIRTABLE_BASE_ID | server | Airtable base ID for subscriber table | Manual |
| NEXT_PUBLIC_STRIPE_PRICE_POWER_DIGITAL_ANNUAL | client | Price ID for Power Digital annual license | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_PQT_SOLO | client | Price ID for Power Queue Tracker Solo plan | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_PQT_TEAM | client | Price ID for Power Queue Tracker Team plan | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_PQT_ENTERPRISE | client | Price ID for Power Queue Tracker Enterprise plan | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_REELPOST_STARTER | client | Price ID for ReelPost Starter plan | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_REELPOST_PRO | client | Price ID for ReelPost Pro plan | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_REELPOST_AGENCY | client | Price ID for ReelPost Agency plan | Generated |
| NEXT_PUBLIC_STRIPE_PRICE_CRYPTO_LOG_PREMIUM | client | Price ID for Crypto Transaction Log Premium plan | Generated |
Related references
See the Stripe Integration Spec for payment flow details, the Operations Runbook for step-by-step procedures, and the Site Map for the complete route inventory.