Iridium

A full-stack starter kit for shipping AI-powered products. Clone the repo, configure your environment, and have a working application with authentication, AI chat, and agent tools in minutes.

Features

• Authentication — Email/password sign-up and sign-in via Better Auth with secure HTTP-only sessions, password reset, and email verification
• Account management — A /settings page with profile editing, password change (revokes other sessions), and account deletion behind a password confirm
• Email — Resend + react-email templates behind a pluggable sendEmail(); without an API key, emails render to the console so local dev needs no provider
• Role-based access control — USER, EDITOR, and ADMIN roles baked into the schema and session helpers, with an /admin panel for role changes, ban/unban, and user impersonation
• AI chat — Conversational interface powered by Mastra and the Vercel AI SDK. Messages persist to PostgreSQL and are organized into searchable threads with per-thread model selection and response regeneration
• Agent tools — The AI assistant can manage notes, fetch live weather, and report the current time, with tool invocations rendered inline in the chat
• Generative UI — The render_card tool lets the agent produce rich visual cards (info, steps, pros/cons) inline in the chat, demonstrating the tool-driven approach to generative UI
• Notes — A full CRUD notes page at /notes with search and pagination; the agent writes to the same store
• Working memory — Mastra remembers user preferences and context across conversations via PostgreSQL-backed working memory
• UX patterns — Light/dark/system theme switching (cookie-based, no flash), flash toast notifications, empty states, reusable form components, offset pagination
• Component library — COSS UI (Base UI primitives styled with Tailwind v4), installed as copy-owned source in app/components/ui/ via the shadcn CLI: bunx shadcn@latest add @coss/<name>
• Production patterns — Soft deletes, Zod-validated env, structured logging, rate limiting, SEO (robots/sitemap/OG tags), husky + lint-staged pre-commit hooks
• Type-safe end to end — Prisma generates types from the schema, Zod validates runtime data, React Router types routes and loaders, CVA ensures type-safe component variants

Tech Stack

Layer	Technology
Framework	React Router (SSR, config-based routing)
UI	React 19, Tailwind CSS v4, COSS UI (Base UI)
Database	PostgreSQL via Prisma ORM
Auth	Better Auth
AI	Mastra, Vercel AI SDK, Anthropic Claude
Validation	Zod, React Hook Form
Runtime	Bun (dev), Node 24 Alpine (production)

Getting Started

Prerequisites

• Bun installed
• Node.js 22.22 or newer (React Router requires it; production runs Node 24)
• Docker installed (for local PostgreSQL)
• Anthropic API key

Quick start

bun install
bun run setup   # interactive: names the app, writes .env, starts Docker,
                # migrates, and seeds demo users in one shot
bun run dev

bun run setup asks for an app name and derives a slug from it (My App → my-app). It writes both to app/config.ts (APP_NAME, APP_SLUG) and uses the slug for the package name, the Docker Compose project, the local database (my_app), the cookie names, and the demo users' emails, so a copy never shares containers, data, or sessions with another copy on the same machine. The databases publish on host ports 5432 and 5433 by default. When another project (the original Iridium, another copy, or a native Postgres) already holds either one, setup offers the next free pair (5442/5443, 5452/5453, ...) and writes it to .env as POSTGRES_PORT and MASTRA_POSTGRES_PORT, with the matching database URLs, so copies can run side by side. When it finishes, it lists what is left to rebrand by hand (favicon, landing copy, README).

It also takes --non-interactive (and --name "<App Name>") for scripted use; it then takes the free ports without asking. To pick them yourself, export POSTGRES_PORT and MASTRA_POSTGRES_PORT before running it. Prefer manual control? The steps below do the same thing by hand. To stand up production on Railway, see Railway.

Installation

bun install

Environment

Copy .env.example to .env and fill in:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/iridium"
MASTRA_DATABASE_URL="postgresql://postgres:postgres@localhost:5433/mastra"
# Host ports for docker-compose.dev.yml; keep the URLs above on the same ports
POSTGRES_PORT="5432"
MASTRA_POSTGRES_PORT="5433"
BETTER_AUTH_SECRET="<openssl rand -base64 32>"
BETTER_AUTH_BASE_URL="http://localhost:5173"
ANTHROPIC_API_KEY="sk-ant-..."

# Optional: real email sending (otherwise emails log to the console)
RESEND_API_KEY="re_..."
EMAIL_FROM="Iridium <[email protected]>"

# Optional: OAuth login buttons (each renders only when both vars are set).
# Callback URLs: <BETTER_AUTH_BASE_URL>/api/auth/callback/<provider>
GITHUB_CLIENT_ID="..."
GITHUB_CLIENT_SECRET="..."
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."

# Optional: first admin. Listed emails become ADMIN once verified.
ADMIN_EMAILS="[email protected]"

Two-Database Setup

The app runs two PostgreSQL instances via docker-compose.dev.yml:

Database	Port	Env Var	Purpose
iridium	5432	DATABASE_URL	Prisma (app data, auth, threads)
mastra	5433	MASTRA_DATABASE_URL	Mastra memory and state

This is the beginning of the README. Read the rest at the original. Read the full README ↗