Oceanic Environmental Research Portal

A full-stack monorepo for ocean environmental researchers to record observations, manage samples, and publish reports.

Stack

Layer	Technology
Frontend	Next.js 16 (App Router), Tailwind CSS v4
Backend	Express 4, TypeScript
Database	PostgreSQL via Prisma 5 (hosted on Supabase)
Auth	Auth0
Storage	AWS S3
AI	Anthropic Claude API
Monorepo	npm workspaces + Turborepo 2

Project Structure

apps/
  web/          Next.js 16 frontend (port 3000)
  api/          Express API (port 4000)
packages/
  database/     Prisma schema, migrations, and client singleton
  types/        Shared TypeScript interfaces and API response envelopes
  ui/           Shared React component library (Tailwind-based)

Local Setup

Prerequisites: Node.js ≥ 18, npm ≥ 9, a PostgreSQL database (Supabase recommended)

1. Install dependencies

npm install

2. Configure environment

cp .env.example .env

Fill in all values in .env. At minimum you need DATABASE_URL and DIRECT_URL to run migrations.

3. Build shared packages

Required once before the first npm run dev, and any time you change package source code.

npm run build:packages

4. Run database migrations

npm run db:migrate

5. Start development

npm run dev

Both servers start in parallel:

• Web: http://localhost:3000
• API: http://localhost:4000
• Health check: http://localhost:4000/health

Scripts

Script	Description
npm run dev	Build packages then start all apps in watch mode
npm run build	Production build all apps and packages
npm run build:packages	Build only the shared packages
npm run lint	Type-check all packages
npm run test	Run all test suites
npm run db:migrate	Run Prisma migrations
npm run db:studio	Open Prisma Studio GUI

Deployment

Frontend (apps/web) → Vercel

Import the repository in Vercel. In Project Settings → General:

• Root Directory: leave blank (Vercel reads vercel.json at root)
• Framework Preset: Next.js (auto-detected)

Backend (apps/api) → Railway or Render

• Build command: npm install && npm run build:packages && npm run build --workspace=apps/api
• Start command: node apps/api/dist/index.js
• Set all non-NEXT_PUBLIC_* environment variables in the platform dashboard.

Database Models

Model	Purpose
ResearchStation	Physical monitoring stations with lat/lon/depth
Researcher	Staff accounts linked to Auth0 identities
OceanObservation	Timestamped readings (temp, salinity, pH, O₂, depth)
DataSample	Physical samples (water/sediment/organism) stored on S3
Report	Published research reports stored on S3