Getting started

Plotra is licensed under the AGPL-3.0. Bug reports, fixes and docs improvements are welcome. For anything larger than a small fix, open an issue first so the approach can be agreed before you spend time on it.

The short version of the rules is in CONTRIBUTING.md at the root of the repository. These pages go into more detail.

Requirements

Bun, the version pinned under packageManager in the root package.json
Git
A Postgres database. A free Neon project works, and so does a local Postgres.

Setup

git clone https://github.com/ItzSudhan/plotra.git
cd plotra
bun install

cp apps/app/.env.example apps/app/.env.local
cp apps/collab/.dev.vars.example apps/collab/.dev.vars

Fill in three values:

Variable	File	Value
`DATABASE_URL`	`apps/app/.env.local`	Your Postgres connection string. On Neon: Connect, then the pooled connection string.
`BETTER_AUTH_SECRET`	`apps/app/.env.local`	`openssl rand -base64 32`
`COLLAB_SECRET`	`apps/app/.env.local` and `apps/collab/.dev.vars`	Another `openssl rand -base64 32`. The same value in both files.

The database role must own the database and be allowed to create roles. One of the migrations creates the plotra_app role that user requests run as.

Then:

bun run db:migrate
bun dev

bun dev runs every app through Turborepo:

App	URL
The app (`apps/app`)	http://localhost:3000
The public site (`apps/web`)	http://localhost:3001
These docs (`apps/docs`)	http://localhost:3002
The collab server (`apps/collab`)	http://localhost:8787

To run less:

bun dev:app    # the app and the collab server
bun dev:web    # the public site
bun dev:docs   # the docs

Optional services

Everything else in apps/app/.env.example is optional, and Plotra has to keep working without it:

Unset	What happens
`RESEND_API_KEY`	Invitation and share emails are printed to the terminal
`R2_*`	Version snapshots and attachments are stored in Postgres
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`	The Google sign-in button is hidden
`NEXT_PUBLIC_POSTHOG_KEY`	Usage events stay in Postgres only
`QUOTA_*`	The hosted version's default limits apply

If your change adds a service, it must be optional in the same way.

Database

The schema is in packages/db/src/schema, and the migrations in packages/db/drizzle.

bun run db:migrate    # apply migrations to your database
bun run db:studio     # browse the data
bun run db:generate   # write a new migration from a schema change

No migrations without discussion

Don't add or edit a migration, or change a table definition, in a pull request that wasn't agreed in an issue first. Migrations run against a database that holds people's manuscripts, their numbers collide between pull requests, and every table needs row-level security policies to match. See How the app works.

Checks

Run these from the repository root before you open a pull request:

bun run lint
bun run typecheck
bun run build
bun scripts/check-licenses.ts   # only if you added a dependency

There is no test suite yet. Try your change in a browser, and with two accounts in two browsers if it touches collaboration. Say in the pull request what you tested and what you didn't.

Where to go next

Monorepo layout: what lives where.
How the app works: server actions, access, errors and the two database connections.
Code style
The roadmap, with notes on what was tested: plan.md.

RequirementsCopy Anchor Link

SetupCopy Anchor Link

Optional servicesCopy Anchor Link

DatabaseCopy Anchor Link

ChecksCopy Anchor Link