Thunderstrux

Thunderstrux is a Docker-based Next.js App Router SaaS for student societies. It supports member and organisation accounts, organisation event management, public event discovery, ticket checkout, and Stripe Connect.

Last reviewed: 2026-04-28

Stack

• Next.js 16 App Router with Turbopack
• React 19
• Auth.js / NextAuth Credentials provider
• Prisma
• PostgreSQL 16
• Tailwind CSS
• Docker Compose
• Stripe Checkout
• Stripe Connect Express
• pnpm

Local Development

Development is Docker-only.

The project .env uses:

DATABASE_URL=postgresql://thunderstrux:thunderstrux@db:5432/thunderstrux?schema=public

The host name db only resolves inside the Docker Compose network. Do not run host next dev with this .env; it will fail to connect to Postgres.

Start the stack:

docker compose up -d

Open:

http://localhost:3000

Database from host:

postgresql://thunderstrux:thunderstrux@localhost:5433/thunderstrux?schema=public

Database from app container:

postgresql://thunderstrux:thunderstrux@db:5432/thunderstrux?schema=public

Common Commands

docker compose up -d
docker compose restart app
docker compose exec app pnpm dev:doctor
docker compose exec app pnpm dev:webpack
docker compose exec app pnpm prisma:migrate
docker compose exec app pnpm prisma:generate
docker compose exec app pnpm seed
docker compose build app
docker compose up -d --build --force-recreate app
docker compose logs -f app

Equivalent package helpers exist for host use:

pnpm docker:up
pnpm docker:restart
pnpm docker:migrate
pnpm docker:seed
pnpm docker:db:sync
pnpm docker:build
pnpm docker:rebuild

DO NOT RUN pnpm build INSIDE CONTAINER

Do not run this against a running app container:

docker compose exec app pnpm build

The production container serves the .next-build output through a running next start process. Running pnpm build inside that same container mutates .next-build while the server still has the previous build manifest in memory. That can desynchronise CSS/static chunks and routes, causing assets to return 404.

Use these commands instead:

pnpm docker:build
pnpm docker:rebuild

If an in-container build was already run, recreate the app container:

docker compose up -d --build --force-recreate app

Account Model

User.accountRole is either:

• member
• organisation

Member accounts can complete a profile, join organisations, browse public events, buy tickets, and view /tickets.

Organisation accounts represent exactly one organisation via Organisation.accountUserId and manage it at /dashboard.

For MVP, organisation committee members may share one organisation login. Future security work should add named staff users, staff invites, MFA, audit logs, and per-user permissions.

Seeded Accounts

All seeded accounts use:

password123

Organisation accounts:

• engineering.org@example.com
• arts.org@example.com
• robotics.org@example.com
• payments.lab@example.com
• empty.org@example.com

Member/test accounts:

• user1@example.com
• user2@example.com
• admin@example.com
• event.manager@example.com
• finance@example.com
• content@example.com
• member@example.com
• empty@example.com
• outsider@example.com

Main Routes

Public:

• /
• /events/[eventId]
• /login
• /signup

Member:

• /dashboard
• /dashboard/organisations
• /tickets

Organisation:

• /dashboard
• /dashboard/create
• /dashboard/events
• /dashboard/events/new
• /dashboard/events/[eventId]/edit
• /dashboard/orders
• /dashboard/settings

Legacy compatibility redirects:

• /dashboard/[orgSlug]
• /dashboard/[orgSlug]/events
• /dashboard/[orgSlug]/events/new
• /dashboard/[orgSlug]/events/[eventId]/edit
• /dashboard/[orgSlug]/orders
• /dashboard/[orgSlug]/settings

Next.js Stability Notes

• Dev output writes to .next.
• Production build output writes to .next-build.
• pnpm dev clears .next/dev before startup.
• pnpm dev uses Turbopack by default.
• pnpm dev:webpack is the safe fallback if Turbopack route manifests or hot reload become unstable.
• pnpm dev:doctor prints a read-only report for stuck dev-server symptoms and stale generated metadata.
• pnpm build runs scripts/prepare-next-build.mjs and prisma generate before next build.
• pnpm build is blocked inside the running production-like app container. Rebuild the image instead.
• tsconfig.json must not include .next/dev/types/**/*.ts; stale dev route types can break production builds.
• The current route guard uses proxy.ts, not deprecated middleware.ts.
• Turbopack root is pinned in next.config.ts so unrelated lockfiles outside the repo do not affect workspace detection.
• scripts/assert-docker-runtime.mjs warns by default, but blocks pnpm dev outside Docker when .env points at db:5432.

Project Structure

app/           App Router pages and API routes
components/    UI and feature components
lib/           Auth, Prisma, validators, Stripe, client helpers
prisma/        Schema, migrations, seed script
docs/obsidian/ Internal codebase notes
docker/        Dockerfile and container setup
scripts/       Local development safety scripts