go-nextjs-ai-saas-starter — Next.js SaaS Template

SHA-256: 7116132c5b395561a179a6ac305ae305570f1925bd59ef19920daebfff2ea23c

2026-10-01T01:10:23.529Z

# Go + Next.js AI SaaS Starter

A development-preview foundation for building multi-tenant AI document operations with Go and Next.js. It combines secure document ingestion, permission-aware retrieval, cited AI answers, typed extraction and review workflows, commercial entitlement boundaries, durable background processing, and audit evidence in one pragmatic modular monolith.

> **Status:** Experimental hobby project currently in active development. This repository is designed for local development and architecture study; it is not production-ready. Real-provider acceptance is not yet recorded for this local-development system. Production deployment, CI/CD, release automation, and operational certification remain roadmap work.

The initial public repository uses `development` as its only/default branch. A stable `main` branch will be created only when the production track is explicitly promoted. Until then, database migrations are a resettable canonical development baseline and may require contributors to recreate local data after a schema change.

![Dashboard preview](docs/dashboard.png)

## What is implemented

- Stytch B2B magic-link authentication with HttpOnly web cookies and a Bearer JWT contract for future mobile/API clients.
- Go-enforced organization context, tenant isolation, canonical `admin`/`manager`/`member` roles, permissions, fresh-session checks, and subscription enforcement.
- PostgreSQL schema-per-module ownership, forced tenant RLS, SQLC, and explicit request/worker/migration database roles.
- PDF upload, ClamAV scanning, S3-compatible local object storage, document versions, OCR, embeddings, hybrid retrieval, permission-aware RAG, and byte-exact citations.
- Typed extraction templates and durable runs, immutable results, human approval/rejection, approved-output publication/export, and signed HTTPS webhook delivery.
- Polar adapters plus local catalog, entitlement, usage, reservation, quota, checkout, portal, and webhook boundaries.
- Product SMTP notifications, immutable audit evidence, transactional outbox, Redis Streams, retry, DLQ, and allowlisted replay tooling.
- OpenTelemetry traces, private Prometheus metrics, structured redacted logs, readiness checks, architecture fitness tests, and synthetic RAG evaluation.

External business providers are never replaced by runtime fakes. A provider is either explicitly disabled or selected with complete configuration; incomplete selected providers fail startup.

## Architecture

The backend is one Go modular-monolith codebase with coordinated API, worker, and bounded operator runtime roles. The architecture is intentionally pragmatic:

- module roots expose public contracts; private application, domain, transport, repository, worker, and provider code stays behind each owner boundary;
- ports and adapters are introduced where ownership, substitution, or external infrastructure requires them, not for every function;
- lifecycle, authorization, provenance, quota, replay, and publication invariants use focused domain types, while straightforward orchestration remains layered application code;
- use cases may be organized as vertical slices inside a module without bypassing the module and layer rules;
- synchronous invariants use direct public contracts, while durable jobs and integration facts use transactional outbox plus Redis Streams;
- Next.js is the UI/SSR layer and calls the versioned Go API directly; it is not a business BFF.

See the [current-system documentation](docs/current-system/README.md) and [architecture overview](docs/architecture/overview.md).

## Technology

- Go 1.26.6, Gin, SQLC, PostgreSQL 17, pgvector, Redis 8 Streams
- Next.js 16.3.0, React 19.2.8, TypeScript, Tailwind CSS 4, TanStack Query
- MinIO for local S3-compatible storage, Mailpit for local product email, ClamAV for upload scanning
- Stytch, Cloudflare R2, Mistral OCR, OpenAI, Polar, generic SMTP, and hardened HTTPS webhooks behind explicit adapters

## Local quick start

Prerequisites:

- Docker Desktop with Docker Compose
- Go 1.26.6
- Node.js 24.19.0 and pnpm 11.20.0
- a Stytch B2B test project for authentication

Select the pinned Node.js and package-manager versions:

```bash
nvm install 24.19.0
nvm use 24.19.0
corepack enable
corepack prepare [email protected] --activate
```

Install frontend dependencies, create local configuration, and start local infrastructure:

```bash
cd frontend
pnpm install --frozen-lockfile
cd ..
chmod +x setup.sh
./setup.sh
```

Add your Stytch test credentials to ignored `backend/app.env`, then start the API, worker, and frontend:

```bash
make dev
```

Local endpoints:

- web: [http://localhost:3000](http://localhost:3000)
- Go API: [http://localhost:8080](http://localhost:8080)
- Swagger UI: [http://localhost:8080/swagger/index.html](http://localhost:8080/swagger/index.html)
- Mailpit product-email UI: [http://localhost:8025](http://localhost:8025)

Mailpit captures only product SMTP messages. Stytch sends authentication and magic-link email through Stytch infrastructure.

## Verification

```bash
make test
make test-integration
make test-e2e
```

Specialist backend gates are available under `backend/`, including `make test-worker`, `make test-race`, `make test-fuzz`, `make rag-eval`, `make sqlc`, `make swagger`, `make lint`, and `make build`. Frontend gates include `pnpm test`, `pnpm lint`, `pnpm typecheck`, `pnpm build`, and `pnpm api:contracts:check`.

Credential-free local tests do not prove real R2, Polar, Mistral, OpenAI, SMTP, Stytch production-domain, public webhook-recipient, authenticated-browser, or native-mobile behavior. See [testing](docs/testing.md) for the exact boundary.

## Documentation

- [Setup](SETUP.md)
- [Development guide](DEVELOPMENT.md)
- [Configuration](docs/configuration.md)
- [Current system](docs/current-system/README.md)
- [Architecture](docs/architecture/overview.md)
- [Backend developer guides](backend/docs/README.md)
- [Frontend developer guides](frontend/docs/README.md)
- [Database ownership](docs/database/schema-ownership-baseline.md)
- [Testing](docs/testing.md)
- [Security](SECURITY.md)
- [Roadmap](docs/roadmap.md)

## License

[MIT License](LICENSE)

## Acknowledgements

This project was originally based on
`moasq/production-saas-starter` by Mohammed Salim
and has since been substantially modified and extended.

The original project is licensed under the MIT License.