Introduction

Start here

Achromatic is a production-grade Next.js SaaS starter kit built as a single, approachable application. This documentation explains what the repository ships, how its systems fit together and where to customize them safely.

What ships

The repository includes working implementations for:

• Next.js 16.3, React 19 and TypeScript 7 with the App Router, Server Components and streaming.
• Prisma ORM and PostgreSQL with schemas, migrations and local Docker setup.
• Better Auth with email and password authentication, Google OAuth, email verification, password recovery, TOTP two-factor authentication and administration.
• Organizations with invitations, roles, permissions and organization-scoped data.
• Stripe billing with subscriptions, one-time purchases, credits, per-seat billing, a customer portal and webhook synchronization.
• Email with Resend, React Email templates and local template previews.
• AI with a working Vercel AI SDK chatbot, persistence and credit consumption.
• Image storage with S3-compatible presigned uploads for avatars and organization logos.
• Developer tooling with tests, strict TypeScript, Oxlint and Oxfmt and a local, read-only MCP server for repository-aware coding assistance.
• Operations with Pino logging, Sentry, Vercel Analytics and Speed Insights.
• Product surfaces including marketing pages, a blog, legal pages, account settings, organization settings and the admin dashboard.

Architecture

Achromatic deliberately uses a single repository and a single Next.js application. Marketing, authentication, the SaaS dashboard and API routes share one dependency graph and deployment. This keeps local development, upgrades and cross-cutting changes direct. It is an intentional alternative to a monorepo, not a reduced version of one.

The application is organized around feature boundaries:

• app/ contains routes, layouts and route handlers.
• components/ contains reusable interface and feature components.
• config/ contains typed product configuration.
• lib/ contains server integrations and application services.
• trpc/ contains the type-safe API layer.
• The database schema and migration directories contain the persistence model.

Use the folder structure and codebase overview before moving large features.

Choose the right database kit

Both repositories ship the same product features and user experience. Choose Prisma when your team prefers Prisma ORM. If you are still deciding, use the starter kit chooser before selecting the repository that will become the foundation for your product.

Recommended path

1. Complete Setup without product customizations.
2. Confirm the application, database, signup and email verification flows work locally.
3. Read Configuration and replace the product identity.
4. Configure only the integrations your first release needs.
5. Run the test and quality checks before changing architecture.
6. Use the deployment guide as a production checklist.

Starting from a verified baseline makes later failures much easier to isolate.

Scope of this documentation

Use these guides as the source of truth for the code Achromatic ships: repository paths, package scripts, configuration files, environment variable names and how the included features are connected. Database-specific pages are kept separate where schema or migration workflows differ between editions.

Use the upstream documentation when you need the complete API of an underlying library:

• Next.js documentation for framework behavior and App Router APIs.
• Better Auth documentation for plugin APIs and authentication concepts.
• Stripe documentation for account configuration, Checkout and webhook behavior.
• The official Prisma ORM documentation for queries, schema syntax and advanced database features.

Check the versions pinned in package.json before following a newly published upstream example. If an upstream guide conflicts with this documentation, first confirm that it targets the same installed version and the same runtime.