Table of Contents

• Key Features
• Quick Start
  • Prerequisites
  • Docker Setup (Recommended)
  • Manual Setup
• Development
• Project Structure
• Deployment
• API Documentation
• Contributing
• License
• Support

Quick Start

Prerequisites

• Node.js 22+ and npm 10+
• PostgreSQL 16+ (or Docker)
• Redis 7+ (or Docker)

Docker Setup (Recommended)

The fastest way to get started with Taskosaur is using Docker Compose:

1. Clone the repository

   git clone https://github.com/Taskosaur/Taskosaur.git taskosaur
   cd taskosaur
   

2. Set up environment variables

   cp .env.example .env
   

   This creates the .env file used for the app, you may customize the values, if you need.

3. Start with Docker Compose

   docker compose -f docker-compose.dev.yml up
   

   This automatically:

   • ✅ Starts PostgreSQL and Redis
   • ✅ Installs all dependencies
   • ✅ Generates Prisma client
   • ✅ Runs database migrations
   • ✅ Seeds the database with sample data
   • ✅ Starts both backend and frontend

4. Access the application

   • Frontend: http://localhost:3001
   • Backend API: http://localhost:3000
   • API Documentation: http://localhost:3000/api/docs

See DOCKER_DEV_SETUP.md for detailed Docker documentation.

Manual Setup

If you prefer to run services locally:

1. Clone the repository

   git clone https://github.com/Taskosaur/Taskosaur.git taskosaur
   cd taskosaur
   

2. Install dependencies

   npm install
   

3. Environment Setup

   Create a .env file in the root directory:

   # Database Configuration
   DATABASE_URL="postgresql://taskosaur:taskosaur@localhost:5432/taskosaur"
   
   # Application
   NODE_ENV=development
   
   # Authentication & Security
   JWT_SECRET="your-jwt-secret-key-change-this"
   JWT_REFRESH_SECRET="your-refresh-secret-key-change-this-too"
   JWT_EXPIRES_IN="15m"
   JWT_REFRESH_EXPIRES_IN="7d"
   
   # Encryption for sensitive data
   ENCRYPTION_KEY="your-64-character-hex-encryption-key-change-this-to-random-value"
   
   # Redis Configuration (for Bull Queue)
   REDIS_HOST=localhost
   REDIS_PORT=6379
   REDIS_PASSWORD=
   
   # Email Configuration (optional, for notifications)
   SMTP_HOST=smtp.example.com
   SMTP_PORT=587
   SMTP_USER=your-email@taskosaur.com
   SMTP_PASS=your-app-password
   SMTP_FROM=noreply@taskosaur.com
   EMAIL_DOMAIN="taskosaur.com"
   
   # Frontend URL (for email links and CORS)
   FRONTEND_URL=http://localhost:3001
   CORS_ORIGIN="http://localhost:3001"
   
   # Backend API URL (for frontend to connect to backend)
   NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api
   
   # File Upload
   UPLOAD_DEST="./uploads"
   MAX_FILE_SIZE=10485760
   
   # Queue Configuration
   MAX_CONCURRENT_JOBS=5
   JOB_RETRY_ATTEMPTS=3
   

4. Setup Database

   # Run database migrations
   npm run db:migrate
   
   # Seed the database (idempotent - safe to run multiple times)
   npm run db:seed
   
   # Or seed with admin user only
   npm run db:seed:admin
   

5. Start the Application

   # Development mode (runs both frontend and backend)
   npm run dev
   
   # Or start individually
   npm run dev:frontend    # Start frontend only (port 3001)
   npm run dev:backend     # Start backend only (port 3000)
   

6. Access the Application

   • Frontend: http://localhost:3001
   • Backend API: http://localhost:3000
   • API Documentation: http://localhost:3000/api/docs

Development

Available Commands

All commands are run from the root directory:

Development

npm run dev              # Start both frontend and backend concurrently
npm run dev:frontend     # Start frontend only (Next.js on port 3001)
npm run dev:backend      # Start backend only (NestJS on port 3000)

Build

npm run build            # Build all workspaces (frontend + backend)
npm run build:frontend   # Build frontend for production
npm run build:backend    # Build backend for production
npm run build:dist       # Build complete distribution package

Database Operations

All seed commands are idempotent and safe to run multiple times:

npm run db:migrate         # Run database migrations
npm run db:migrate:deploy  # Deploy migrations (production)
npm run db:reset           # Reset database (deletes all data!)
npm run db:seed            # Seed database with sample data
npm run db:seed:admin      # Seed database with admin user only
npm run db:generate        # Generate Prisma client
npm run db:studio          # Open Prisma Studio (database GUI)
npm run prisma             # Run Prisma CLI commands directly

Testing

npm run test               # Run all tests
npm run test:frontend      # Run frontend tests
npm run test:backend       # Run backend unit tests
npm run test:watch         # Run backend tests in watch mode
npm run test:cov           # Run backend tests with coverage
npm run test:e2e           # Run backend end-to-end tests

Code Quality

npm run lint               # Lint all workspaces
npm run lint:frontend      # Lint frontend code
npm run lint:backend       # Lint backend code
npm run format             # Format backend code with Prettier

Cleanup

npm run clean              # Clean all build artifacts
npm run clean:frontend     # Clean frontend build artifacts
npm run clean:backend      # Clean backend build artifacts

Git Hooks

Automatic code quality checks with Husky:

• Pre-commit: Runs linters on all workspaces before each commit
• Ensures code quality and consistency
• Bypass with --no-verify (emergencies only)

git commit -m "feat: add feature"  # Runs checks automatically

Project Structure

taskosaur/
├── backend/                # NestJS Backend (Port 3000)
│   ├── src/
│   │   ├── modules/       # Feature modules
│   │   ├── common/        # Shared utilities
│   │   ├── config/        # Configuration
│   │   └── gateway/       # WebSocket gateway
│   ├── prisma/            # Database schema and migrations
│   ├── public/            # Static files
│   └── uploads/           # File uploads
├── frontend/              # Next.js Frontend (Port 3001)
│   ├── src/
│   │   ├── app/          # App Router pages
│   │   ├── components/   # React components
│   │   ├── contexts/     # React contexts
│   │   ├── hooks/        # Custom hooks
│   │   ├── lib/          # Utilities
│   │   └── types/        # TypeScript types
│   └── public/           # Static assets
├── docker/               # Docker configuration
│   └── entrypoint-dev.sh # Development entrypoint script
├── scripts/              # Build and utility scripts
├── .env.example          # Environment variables template
├── docker-compose.dev.yml # Docker Compose for development
└── package.json          # Root package configuration

Conversational AI Task Execution Setup

Enable Conversational AI Task Execution in 3 Steps:

1. Navigate to Organization Settings

   Go to Settings → Organization Settings → AI Assistant Settings
   

2. Add Your LLM API Key

   • Toggle "Enable AI Chat" to ON
   • Add your API key from any compatible provider:
     • OpenRouter (100+ models, free options): https://openrouter.ai/api/v1
     • OpenAI (GPT models): https://api.openai.com/v1
     • Anthropic (Claude models): https://api.anthropic.com/v1
     • Local AI (Ollama, etc.): Your local endpoint

3. **Star