Development Setup

This guide covers everything you need to contribute code to Reqcore.

Prerequisites

Node.js 18.20+ (LTS 20+ recommended)
Docker and Docker Compose
Git
A code editor (VS Code recommended)

Getting Started

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/reqcore.git
cd reqcore

# 2. Copy environment file
cp .env.example .env
# Or run setup.sh to generate random secrets:
./setup.sh

# 3. Start infrastructure services
docker compose up -d

# 4. Install dependencies
npm install

# 5. Start the dev server
npm run dev

The app is available at http://localhost:3000.

Development Commands

Command	Purpose
`npm run dev`	Start Nuxt development server
`npm run build`	Build for production
`npm run preview`	Preview production build
`npm run db:generate`	Generate a migration after schema changes
`npm run db:migrate`	Apply pending migrations
`npm run db:push`	Push schema changes directly (dev only)
`npm run db:studio`	Open Drizzle Studio (database GUI)
`npm run db:seed`	Seed the database with sample data
`npm run test:e2e`	Run Playwright end-to-end tests

Branch and Commit Workflow

Create a topic branch from main:
```
git checkout -b feat/my-feature
```
Make your changes with focused, atomic commits
Sign every commit with the DCO (Developer Certificate of Origin):
```
git commit -s -m "feat: add candidate search"
```
Push and open a pull request with a clear summary

DCO Sign-Off

Reqcore uses the Developer Certificate of Origin instead of a CLA. Every commit must include a Signed-off-by: line. Pull requests fail CI if commits are missing sign-off.

Coding Conventions

Project Structure

Follow Nuxt 4 app/ + root server/ directory structure
Client code goes in app/ — never put components in server/
Server code stays at the project root — never put API routes in app/
Content files go in content/ — not inside app/

Styling

Use Tailwind CSS v4 utilities — no custom CSS unless absolutely necessary
Use lucide-vue-next for icons (tree-shakeable, consistent)
Dark theme pages use bg-[#09090b] with glass-like borders (border-white/[0.06])

Server Code

Access environment variables through env from server/utils/env.ts — never use process.env directly
Scope every database query by organizationId from the session
Use createError() for HTTP errors — never return error objects
Validate all input with Zod schemas via readValidatedBody / getValidatedQuery

Client Code

Use useFetch or useAsyncData for data fetching — never $fetch in component setup
Forward cookies during SSR: headers: useRequestHeaders(['cookie'])
Use useSeoMeta() for SEO meta tags
Use definePageMeta() for page configuration (layout, middleware)

Pull Request Checklist

Scoped changes to one concern
Tested the change locally
Updated documentation if behavior changed
No tenant-scope or auth regressions
All commits are DCO signed (git commit -s)

Next Steps

Coding Conventions — Detailed style guide
Architecture Overview — Understanding the system
Introduction — Product context