Contributing

Get Dictumal running locally and start contributing.

Prerequisites

Node.js 18+ and npm
PostgreSQL database (local or hosted)
A Google Cloud OAuth client (for authentication)
An OpenRouter API key (for AI features)
A DigitalOcean API token (required only if testing deployment flows)

Local Setup

Clone the repo

git clone https://github.com/your-org/dictumal.git
cd dictumal/dictumal

Install dependencies
```
npm install
```

Set up environment variables

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

DATABASE_URL="postgresql://user:pass@localhost:5432/dictumal"
AUTH_URL="http://localhost:3000"
AUTH_SECRET="your-random-secret"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
OPENROUTER_API_KEY="your-openrouter-key"
DIGITALOCEAN_API_TOKEN="your-do-token"  # optional
DIGITALOCEAN_IMAGE_SLUG="ubuntu-24-04-x64"  # optional explicit pin
DIGITALOCEAN_USE_LATEST_UBUNTU_IMAGE="false"  # optional; defaults to false
DIGITALOCEAN_SSH_KEYS="123456,aa:bb:cc:dd"  # optional DO SSH key ids/fingerprints
NEXT_PUBLIC_STREAM_GATEWAY_HOST="stream.the-next-lab.com"  # optional launch host override

Run database migrations
```
npx prisma migrate dev
```
Generate the Prisma client
```
npx prisma generate
```
Start the dev server
```
npm run dev
```
Open http://localhost:3000 in your browser.

Google OAuth Setup for Local Dev

In your Google Cloud Console OAuth client configuration, add:

Authorized JavaScript origins: http://localhost:3000
Authorized redirect URIs: http://localhost:3000/api/auth/callback/google

Project Structure

All application code lives in the dictumal/ subdirectory:

src/app/ — Next.js App Router pages and API routes
src/components/ — Reusable React components
src/lib/ — Shared utilities (auth, Prisma, AI, deploy)
prisma/ — Database schema and migrations

Common Commands

Command	Description
`npm run dev`	Start the development server
`npm run build`	Build for production
`npx prisma migrate dev`	Run pending migrations
`npx prisma generate`	Regenerate the Prisma client after schema changes
`npx prisma studio`	Open the Prisma database GUI

Environment Variables

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`NEXTAUTH_URL`	Yes	Legacy alias for auth base URL (prefer `AUTH_URL`)
`NEXTAUTH_SECRET`	Yes	Legacy alias for auth secret (prefer `AUTH_SECRET`)
`AUTH_URL`	Yes	Base URL used by NextAuth v5
`AUTH_SECRET`	Yes	Session/JWT signing secret used by NextAuth v5
`GOOGLE_CLIENT_ID`	Yes	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Yes	Google OAuth client secret
`OPENROUTER_API_KEY`	Yes	OpenRouter API key for AI features
`DIGITALOCEAN_API_TOKEN`	Required for deploy	DigitalOcean API token for droplet create/get/delete
`DIGITALOCEAN_IMAGE_SLUG`	No	Override droplet image slug (default is pinned ubuntu-24-04-x64)
`DIGITALOCEAN_USE_LATEST_UBUNTU_IMAGE`	No	If true, auto-select latest Ubuntu image from DigitalOcean catalog
`DIGITALOCEAN_SSH_KEYS`	No	Comma-separated DigitalOcean SSH key IDs or fingerprints
`NEXT_PUBLIC_STREAM_GATEWAY_HOST`	No	Preferred host for launch redirects. Defaults to `stream.the-next-lab.com`; falls back to deployment IP when blank.

Deployment Debug Checklist

DIGITALOCEAN_API_TOKEN present and not placeholder text.
Account has droplet quota and selected region/size capacity.
If route calls return 401, verify auth env values and Google OAuth callback URL alignment.
If deployment times out, inspect droplet /var/log/dictumal-init.log.