Study Desk is a self-hosted, single-user study application.

## Local development

```powershell
npm.cmd ci
npx.cmd prisma generate
npm.cmd run dev
```

The automated test harness always creates a uniquely named database under
`.test-databases/`, applies committed migrations, and removes the database after
the run. It refuses `dev.db`, `/app/data/study.db`, existing databases, and paths
that are not explicitly test-named.

## Production container

Set a unique session secret of at least 32 characters. Production startup fails
before migrations or the HTTP server when the secret is missing, short, or the
published development fallback.

```powershell
$env:SESSION_SECRET = '<at-least-32-random-characters>'
docker compose -f docker-compose.yml up --build
```

The host listens on `http://localhost:3000`; the container listens on port 3726.
Development Compose is intentionally explicit and is never auto-merged:

```powershell
docker compose -f docker-compose.dev.yml up --build
```

For first-time production setup, either provide an Argon2 encoded
`ADMIN_PASSWORD_HASH`, or temporarily set `ALLOW_INITIAL_SETUP=true` for the
one-time setup request. Remove the flag after setup. Production HTTP password
reset initiation is unavailable; run this on the server instead:

```powershell
npm.cmd run auth:reset
```

If TLS terminates at a trusted reverse proxy, forward requests only from that
proxy and set `SECURE_COOKIES=true`. Leave it false for intentional plain HTTP;
Secure cookies cannot be used over plain HTTP.

## Database backup, migration adoption, and restore

Never run migration tests against the only copy of a study database. Create a
lock-safe SQLite backup through the backup API and verify it before deployment:

```powershell
$env:DATABASE_URL = 'file:./data/study.db'
npm.cmd run db:backup -- --output ./backups/study-before-upgrade.db
npm.cmd run db:preflight
npx.cmd prisma migrate deploy
```

The material-group preflight reports one of four states:

- `APPLY`: migration history is complete and the group schema is absent; run
  `prisma migrate deploy` normally.
- `ADOPT`: prior migrations are tracked and the database exactly matches the
  intended schema of one or more unrecorded committed migrations. This includes
  recovery from P3018 when an already schema-pushed table or column exists.
  After reviewing the verified backup, explicitly run
  `npm run db:preflight -- --resolve --backup <backup-path>`.
- `CURRENT`: migration and schema already agree.
- `CONFLICT`: partial or unknown state. Stop and recover manually; do not use
  `db push`, reset, edit applied migrations, or mark anything applied.

The production entrypoint runs this preflight before `prisma migrate deploy`.
It refuses `ADOPT` and `CONFLICT` states without changing migration history;
adoption always remains an explicit backup-gated operator action.

Restore drill: stop Study Desk, keep the damaged database as evidence, restore
the verified backup to a new path, run SQLite `integrity_check` plus
`npm run db:preflight`, start the same prior application image against the
restored path, and compare class/deck/quiz counts plus representative content.
Only swap the production path after those checks pass.

## Getting Started

First, run the development server:

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.

This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.

## Learn More

To learn more about Next.js, take a look at the following resources:

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!

## Deploy on Vercel

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.