Documentation

A practical guide to this monorepo: what lives where, how to run it, and how to extend the API and database safely.

Overview

This starter combines a Next.js web app, a Hono API on Node, a Prisma database package, and shared TypeScript packages. Authentication is wired for Supabase Auth with cookie-friendly sessions on the API where applicable.

Use this document as a map; replace product-specific copy and routes as your application grows.

Repository layout

  • apps/web — Next.js App Router UI, marketing pages, auth screens, and the authenticated dashboard.
  • apps/api — Hono server with versioned routes under /api/v1/..., Zod + OpenAPI schemas, and thin handlers that delegate to services.
  • packages/database — Prisma schema, migrations workflow, and generated client consumed by the API.
  • packages/types — Shared constants and types (for example enums aligned with the API).

Task orchestration uses pnpm workspaces and Turbo so builds and checks stay cached and predictable.

Environment variables

Keep secrets out of source control. Typical development uses root-level env files such as .env.development (exact names depend on your setup). At minimum you will need:

  • Web — NEXT_PUBLIC_API_URL pointing at your running API (for example http://localhost:3000), plus Supabase public keys used by the browser client.
  • API — Supabase URL and keys, JWT-related settings, database URLs, and CORS origins that match your web origin.
  • Database package — DATABASE_URL and DIRECT_URL for Prisma (often the same host with different connection modes for hosted Postgres).

Validate required variables at startup in small config modules rather than scattering raw process.env reads across handlers.

Local development

From the repository root, install dependencies, then start the apps you need:

  • pnpm install
  • Run the web app (default port may be 3001 in this project) and the API per your package.json scripts.
  • Apply database schema changes through the database package scripts (for example migrate in development) so migration files are generated by Prisma, not edited by hand.

Point NEXT_PUBLIC_API_URL at the API base URL your browser can reach, including during Docker or tunnel-based setups.

API conventions

Routes are auto-loaded from apps/api/src/routes. Each module exports a path (for example /api/v1/health) and a Hono app instance registered with @hono/zod-openapi.

  • Request and response shapes live next to the code under apps/api/src/schema/v1.
  • Business logic belongs in services/ with Prisma and Supabase clients injected from the request context.
  • Only specific URL patterns run the JWT authorization middleware; public routes (health, selected auth endpoints, marketing data) stay reachable without a session.

When the API is running, interactive OpenAPI documentation is usually served at the /docs path on the API origin (confirm in your deployment). Use it to try requests and to share contracts with frontend teammates.

Database workflow

The Prisma schema in packages/database/prisma/schema.prisma is the source of truth for tables and enums. After you change the schema, create migrations using the scripts defined in packages/database/package.json so SQL remains consistent and reviewable in pull requests.

Generated Prisma Client is imported from the @repo/database workspace package; do not commit generated client output from node_modules.

Authentication model

End users sign up and sign in through flows that talk to the API and Supabase. Access tokens may be delivered via HTTP-only cookies for browser clients, while the same API can accept Authorization: Bearer headers for programmatic clients.

Protected routes should assume nothing about the user until the authorization middleware has attached c.get("user"); use small helpers to enforce roles when you add admin or billing surfaces.

Frontend routing

Marketing routes (home, documentation, legal pages) share a shell with the global navigation and footer. Authentication routes under /auth/... use focused layouts suitable for sign-in and recovery flows. Dashboard routes live behind authentication on the client and should call protected API endpoints for data.

Going to production

  • Set production environment variables for web and API, including exact cookie and CORS domains.
  • Run database migrations as part of your deploy pipeline.
  • Turn on structured logging and log sampling appropriate to your traffic.
  • Review rate limits and bot protection for public write endpoints (for example community reviews).

Return to the home page, read the terms of service, or review the privacy policy.