LabAnimal

Home Features Pricing Docs GitHub EN | 中文

Documentation Center

From installation to production deployment, get started with LabAnimal quickly

🚀

🚀 Quick Start

Prerequisites

Node.js ≥ 20
pnpm ≥ 9
PostgreSQL ≥ 15

1. Clone Repository

# Clone the project
git clone https://github.com/xxjzone01-cyber/labanimal.git
cd labanimal

# Install dependencies
pnpm install

2. Configure Database

# Copy environment variable template
cp packages/api/.env.example packages/api/.env

# Edit .env, set PostgreSQL connection string
# DATABASE_URL="postgresql://user:password@localhost:5432/labanimal"

# Run database migration
pnpm --filter @labanimal/db push

# Generate Prisma Client
pnpm --filter @labanimal/db generate

# Seed sample data (optional)
pnpm --filter @labanimal/db seed

3. Start Dev Server

# Start API + frontend simultaneously (Turborepo)
pnpm dev

# API: http://localhost:3001
# Frontend: http://localhost:5173

4. Run Tests

# Run all tests (103 test cases)
pnpm --filter @labanimal/api test

# Watch mode
pnpm --filter @labanimal/api test:watch

📡 API Reference

API base path: /api, all endpoints require JWT Bearer Token (except register/login).

Authentication

Method	Path	Description
`POST`	`/api/auth/send-code`	Send email verification code
`POST`	`/api/auth/register`	Register (requires verification code)
`POST`	`/api/auth/login`	Login, returns JWT

Animal Management

Method	Path	Description
`GET`	`/api/animals?labId=xxx`	Get animal list
`POST`	`/api/animals`	Create animal
`PUT`	`/api/animals/:id`	Update animal
`DELETE`	`/api/animals/:id`	Delete animal

Health Records

Method	Path	Description
`GET`	`/api/health-records?labId=xxx`	Get health records
`POST`	`/api/health-records`	Create health record

IACUC Protocols

Method	Path	Description
`GET`	`/api/protocols?labId=xxx`	Get protocol list
`POST`	`/api/protocols`	Create protocol
`PUT`	`/api/protocols/:id`	Update protocol

Report Signing

Method	Path	Description
`POST`	`/api/license/sign`	RSA sign report
`POST`	`/api/license/verify`	Verify signature
`GET`	`/api/license/verify/:hash`	Public verification via hash

Other Modules

Module	Path Prefix	Description
Rooms / Cages	`/api/rooms, /api/racks, /api/cages`	Facility management
Breeding	`/api/breedings`	Breeding records + weaning
Death Reports	`/api/death-reports`	Death records
Medications	`/api/medications`	Medication records
Audit Log	`/api/audit-log`	SHA-256 hash chain audit
Electronic Signatures	`/api/electronic-signatures`	21 CFR Part 11 signatures
Training	`/api/trainings`	Personnel training records
API Keys	`/api/api-keys`	Programmatic access keys
Subscriptions	`/api/subscriptions`	Stripe / PayPal subscriptions

✅ Compliance Module

AVMA Euthanasia Validation

Built-in AVMA Guidelines 2020 rule engine, automatically matches compliant euthanasia methods by species, age, and equipment.

• Auto-recommend compliant methods
• Auto-block non-compliant methods
• Witness signature confirmation

Dynamic Cage Density

Based on NRC Guide 2011 standard, real-time calculation of maximum housing density.

• Supports mouse/rat/hamster/guinea pig/rabbit
• Auto-lock cages when limit exceeded
• Real-time weight + cage area calculation

21 CFR Part 11 Electronic Signatures

Meets FDA electronic records and electronic signature regulatory requirements.

• SHA-256 hash chain audit trail
• Signature meaning declaration
• Tamper-proof signatures

AAALAC Audit Preparation

One-click generation of reports required for AAALAC certification.

• Annual animal use report
• Mortality statistics
• Protocol compliance rate

🏗️ Deployment Guide

Option A: SaaS (Recommended)

Use labanimal.cloud directly, no need to deploy yourself.

Visit labanimal.cloud/register
Register with email verification
Choose a plan (Academic Free is forever free)
Create a lab and start using

Option B: Self-Deploy

# 1. Clone and install
git clone https://github.com/xxjzone01-cyber/labanimal.git
cd labanimal && pnpm install

# 2. Build
pnpm build

# 3. Configure environment variables
cp packages/api/.env.example packages/api/.env
# Edit .env to set DATABASE_URL, AUTH_SECRET, etc.

# 4. Run database migration
pnpm --filter @labanimal/db push
pnpm --filter @labanimal/db generate

# 5. Start API
cd packages/api && node dist/index.js

# 6. Deploy frontend (packages/app/dist) to any static hosting

Option C: Private Deployment (Enterprise)

For organizations needing full data control, starting at $5,000 (one-time payment).

Offline license code, no internet verification required
30-day grace period
Includes installation support
View offline license purchase page →

🔧 Environment Variables

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`AUTH_SECRET`	Required in production	JWT signing key (≥32 characters)
`PORT`	No	API port, default 3001
`CORS_ORIGIN`	Required in production	Allowed frontend domain
`BREVO_API_KEY`	Yes	Brevo email service key
`LICENSE_PRIVATE_KEY`	No	RSA private key (for report signing)
`LICENSE_PUBLIC_KEY`	No	RSA public key (for signature verification)