Deploy and Host Payzon Monorepo on Railway

Payzon is a Brazilian fintech/education SaaS platform built as a Turborepo monorepo. It includes a Fastify 5 REST API, a React + Vite SPA frontend, a shared Prisma database layer, auto-generated API client, and a Radix-based UI component library — all orchestrated with pnpm workspaces.

About Hosting Payzon Monorepo

Deploying Payzon requires running two main services: the Fastify API backend and a static/SPA build for the React frontend. Both share internal packages (database, UI, utils) that must be built in dependency order via Turborepo. The backend needs a PostgreSQL 16 database for user accounts, education content, and lesson progress tracking, plus a Redis 7 instance for session storage and rate limiting. Object storage (S3-compatible) is required for user avatars and media thumbnails — Cloudflare R2 in production. External integrations include Asaas (payment gateway), Resend (transactional email), and Vimeo (video hosting for lessons).

Common Use Cases

• Hosting a subscription-based education platform with video lessons, module progress tracking, and user management for the Brazilian market
• Running a Fastify API with Better Auth cookie-based authentication, PostgreSQL persistence, and Redis-backed sessions behind a single deployment pipeline
• Deploying a Turborepo monorepo where a React SPA frontend and a Node.js API backend share packages (Prisma schema, UI components, TypeScript configs) and need coordinated builds

Dependencies for Payzon Monorepo Hosting

• PostgreSQL 16 — primary database for users, sessions, education modules, lessons, and progress tracking
• Redis 7 — session storage for Better Auth and rate limiting via Fastify

Deployment Dependencies

• Turborepo — monorepo build orchestration with topological dependency resolution
• pnpm — package manager with workspace support (v10.32)
• Prisma — ORM and migration runner (prisma migrate deploy must run before the API starts)
• Fastify — backend framework (v5) serving the REST API
• Vite — frontend build tool producing a static SPA bundle
• Better Auth — authentication library with Prisma adapter and Redis session store
• Kubb — API client codegen from OpenAPI spec (build-time dependency)

Implementation Details

The monorepo uses a single root .env file consumed by all apps and packages. Key environment variables required for deployment:

# Database
DATABASE_URL=postgresql://user:password@host:5432/payzon

# Redis
REDIS_URL=redis://host:6379

# S3-compatible storage (Cloudflare R2 in production)
S3_ENDPOINT=https://your-account.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET_NAME=payzon

# Auth
BETTER_AUTH_SECRET=your-auth-secret
BETTER_AUTH_URL=https://api.yourdomain.com

# External services
ASAAS_API_KEY=your-asaas-key
RESEND_API_KEY=your-resend-key

The Turborepo build pipeline ensures packages are built in the correct order:

# Build all apps and packages in dependency order
pnpm turbo build

# Run database migrations before starting the API
pnpm prisma migrate deploy

# Start the API (Fastify, default port 5102)
pnpm --filter @repo/api start

# The frontend is a static SPA — serve the dist/ output from apps/app

The API exposes an OpenAPI 3.1 spec at /reference (via Scalar) and serves on port 5102 by default. The frontend SPA expects the API URL to be configured and uses auto-generated TanStack Query hooks from the @repo/api-client package.

Why Deploy Payzon Monorepo on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Payzon Monorepo on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.