Stack & Setup Guide

Prerequisites

Node.js 18.0 or higher (LTS recommended)
PostgreSQL 14 or higher (running and accessible)
npm (included with Node.js) or an equivalent package manager
Git for version control

Installation

1. Clone the Repository

git clone https://github.com/sistershield/sistershield.git
cd sistershield

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the project root. The following variables are required:

# Database
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"

# NextAuth
NEXTAUTH_SECRET="your-random-secret-string"
NEXTAUTH_URL="http://localhost:3000"

# LLM Provider ("anthropic" or "openai")
LLM_PROVIDER="anthropic"

# Anthropic (required if LLM_PROVIDER=anthropic)
ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (required if LLM_PROVIDER=openai, also required for image generation)
OPENAI_API_KEY="sk-..."

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`NEXTAUTH_SECRET`	Yes	Random string for JWT signing (generate with `openssl rand -base64 32`)
`NEXTAUTH_URL`	Yes	Base URL of the application (e.g., `http://localhost:3000`)
`LLM_PROVIDER`	No	`anthropic` (default) or `openai`
`ANTHROPIC_API_KEY`	Conditional	Required when using Anthropic as LLM provider
`OPENAI_API_KEY`	Conditional	Required when using OpenAI as LLM provider, or for image generation (DALL-E 3 always uses OpenAI)

4. Set Up the Database

# Generate the Prisma client
npm run db:generate

# Push the schema to your database (creates tables)
npm run db:push

# Seed the database with test data
npm run db:seed

After seeding, the following test accounts are available:

Role	Email	Password
Teacher	`teacher@sistershield.edu`	`teacher123`
Student	`student@sistershield.edu`	`student123`

5. Start Development Server

npm run dev

The app runs at http://localhost:3000. The default locale redirects to /ko-KR/ (Korean).

Development Commands

Command	Description
`npm run dev`	Start Next.js development server with hot reload
`npm run build`	Production build
`npm run start`	Start production server
`npm run lint`	Run ESLint
`npm run db:generate`	Regenerate Prisma client after schema changes
`npm run db:push`	Push schema changes to database (no migration history)
`npm run db:migrate`	Create and apply a migration (with history)
`npm run db:studio`	Open Prisma Studio (database GUI at localhost:5555)
`npm run db:seed`	Seed database with test data
`npm run test:e2e`	Run Playwright E2E tests (headless)
`npm run test:e2e:ui`	Run Playwright tests with interactive UI
`npm run test:e2e:headed`	Run Playwright tests in headed browser

Build and Deployment

Production Build

npm run build
npm run start

The build step compiles the Next.js application. The start step serves the production build on port 3000 (or the PORT environment variable).

Database Migrations

For production, use Prisma Migrate instead of db push:

npx prisma migrate deploy

This applies all pending migrations without prompting for confirmation.

Environment Notes

Ensure NEXTAUTH_URL matches the deployed URL (including protocol and port).
For HTTPS deployments, Next.js sets the session cookie with Secure flag automatically.
Security headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy) are configured in next.config.js.

Docs Site Development

The documentation site is built with Astro Starlight and lives in the docs-site/ directory.

cd docs-site
npm install
npm run dev

The docs site runs at http://localhost:4321/docs/ by default. Content files are in docs-site/src/content/docs/en/ (English) and docs-site/src/content/docs/ko/ (Korean).

To build the docs for production:

cd docs-site
npm run build

Project Structure Reference

sistershield/
  src/
    app/
      [locale]/(auth)/       Authentication pages
      [locale]/(dashboard)/  Protected dashboard pages
      api/                   REST API routes
      globals.css            Design tokens and base styles
    components/              React components
    lib/                     Shared utilities and services
    hooks/                   Custom React hooks
    messages/                i18n translation files
  prisma/
    schema.prisma            Database schema
    seed.ts                  Seed script
  docs-site/                 Astro Starlight documentation
  tests/                     Playwright E2E tests
  public/                    Static assets
  next.config.js             Next.js + next-intl configuration
  tailwind.config.ts         Tailwind CSS + design token mapping
  package.json               Dependencies and scripts
  tsconfig.json              TypeScript configuration