Beagle App v2

Monorepo for a public Beagle database app supporting breeders, managed by Suomen Beaglejarjesto (Finska Beagleklubben).

Project snapshot

Beagle App v2 is a production-style monorepo for a public Beagle database supporting breeders and managed by Suomen Beaglejarjesto (Finska Beagleklubben).

• Next.js + React + TypeScript full-stack application
• Monorepo architecture with separate web/server/db/contracts/api-client packages
• PostgreSQL + Prisma for schema, migrations, and data access
• Authentication and admin-ready routing for association-managed operations
• Documented operational workflows for environment safety, imports, and deployment

Quick links

• Architecture rules and boundaries: docs/architecture.md
• Developer workflow and agent rules: AGENTS.md
• Documentation rules: docs/documentation-rules.md
• Tech debt register: docs/tech-debt.md
• App usage guide: docs/app-usage-and-features.md
• Env safety and runbooks: docs/ops-env-safety.md
• Import behavior details: docs/legacy-import/import-flow.md
• Azure deployment notes: docs/azure-app-service-deployment.md
• Vercel deployment notes: docs/vercel-deployment.md
• Changelog: CHANGELOG.md

Requirements

• Node.js 20+
• pnpm 10+
• PostgreSQL for app data
• MariaDB only for phase-1 legacy import

Quick start (local)

All commands assume repository root (beagle-app-v2/).

1. Copy local environment template:

cp .env.example .env.local

2. Update .env.local with values for your machine. Required for first run:

• DATABASE_URL (PostgreSQL)
• BETTER_AUTH_SECRET (minimum 32 characters)
• KOIRATIETOKANTA_RESULTS_API_SECRET (required when testing the AJOK result upsert API)

Useful for admin login setup:

• BOOTSTRAP_ADMIN_EMAIL
• BOOTSTRAP_ADMIN_PASSWORD

Needed only for legacy import:

• LEGACY_DATABASE_URL (MariaDB)

3. Install dependencies:

pnpm install

4. Generate Prisma client:

pnpm db:generate

5. Apply committed migrations (recommended):

pnpm db:deploy

Optional local-only shortcut (no migration files applied):

pnpm db:push

6. Start local web app:

pnpm dev

Default URL: http://localhost:3000

7. Optional: bootstrap first admin user:

pnpm auth:bootstrap-admin

Environment safety

For staging/prod commands and explicit env-file loading, use:

• Pre-flight checklist
• Safe command templates

Common dev commands

pnpm typecheck
pnpm lint
pnpm test
pnpm build

Targeted checks:

pnpm --filter @beagle/web test:unit
pnpm --filter @beagle/server test:unit
pnpm --filter @beagle/db test
pnpm --filter @beagle/web test:e2e

DB and auth helpers

pnpm db:studio
pnpm audit:prune
pnpm auth:generate
pnpm auth:migrate
pnpm auth:bootstrap-admin
pnpm auth:set-password

Deploy

Azure production deploys from main through GitHub Actions. See docs/azure-app-service-deployment.md for the required repository and App Service configuration.

Vercel build command:

pnpm vercel:build

See docs/vercel-deployment.md for supported Vercel project setups.

Notes

• README is intentionally minimal and usage-focused.
• Detailed feature behavior, API surface, and implementation conventions are in docs/app-usage-and-features.md.
• Documentation workflow and future cleanup note conventions are in docs/documentation-rules.md and docs/tech-debt.md.
• Source of truth for architecture and dependency boundaries is docs/architecture.md.