Local Development Setup¶

Get your local development environment up and running quickly.

Prerequisites¶

Required Software¶

Node.js: Version 18.x or 20.x
npm: Comes with Node.js (version 9+ recommended)
Git: For version control
MongoDB: Local instance or MongoDB Atlas connection
Google Cloud SDK: For cloud storage integration (optional for basic development)

System Requirements¶

OS: macOS, Linux, or Windows 10/11
RAM: Minimum 8GB recommended
Storage: At least 2GB free space

Installation Steps¶

1. Clone Repository¶

git clone https://github.com/csc301-2025-y/project-8-chkl.git
cd project-8-chkl

2. Install Node.js Dependencies¶

cd hkfr
npm install

This will install all required packages including: - Next.js 15 and React 19 - Development tools (Vitest, ESLint) - Database drivers (MongoDB) - File processing libraries

3. Environment Configuration¶

Create your environment file:

cp .env.example .env

Edit the .env file with your configuration:

# Database Configuration
MONGO=mongodb://localhost:27017/hkfr
DATABASE=hkfr

# JWT Secrets (generate strong random strings)
JWT_SECRET=your-super-secret-jwt-key-here
JWT_REFRESH_SECRET=your-super-secret-refresh-key-here

# Google Cloud Storage (optional for local dev)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GCS_BUCKET_NAME=your-bucket-name

# Application Settings
NODE_ENV=development

Security Note

Never commit your .env file to version control. It contains sensitive information.

4. Database Setup¶

Option A: Local MongoDB¶

Install MongoDB Community Edition
Start MongoDB service
Create database: use hkfr

Option B: MongoDB Atlas (Cloud)¶

Create MongoDB Atlas account
Create a cluster
Get connection string
Update MONGO in .env file

5. Start Development Server¶

npm run dev

The application will be available at: http://localhost:3000

Development Commands¶

Essential Commands¶

# Start development server with Turbopack
npm run dev

# Run tests (watch mode)
npm run test

# Run tests once
npm run test:run

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

# Start production server
npm run start

# Lint code
npm run lint

Advanced Commands¶

# Run specific test file
npm run test -- auth.test.js

# Run tests in specific directory
npm run test -- src/app/api/

# Build and analyze bundle
npm run build && npm run analyze

Development Workflow¶

1. Feature Development¶

graph LR
    A[Create Branch] --> B[Code Changes]
    B --> C[Write Tests]
    C --> D[Run Tests]
    D --> E[Lint Code]
    E --> F[Commit]
    F --> G[Push Branch]
    G --> H[Create PR]

2. Daily Development Routine¶

Pull Latest Changes:
```
git checkout main
git pull origin main
```

Create Feature Branch:

git checkout -b feature/your-feature-name

Start Development Server:
```
npm run dev
```
Make Changes: Edit code in your preferred editor
Run Tests Frequently:
```
npm run test
```

Commit Changes:

git add .
git commit -m "descriptive commit message"

Project Structure Deep Dive¶

Application Structure (`hkfr/src/`)¶

src/
├── app/                     # Next.js App Router
│   ├── page.jsx            # Homepage
│   ├── layout.js           # Root layout
│   ├── globals.css         # Global styles
│   ├── api/                # Backend API routes
│   │   ├── auth/           # Authentication endpoints
│   │   │   ├── login/route.js
│   │   │   ├── register/route.js
│   │   │   ├── refresh/route.js
│   │   │   └── logout/route.js
│   │   ├── manage_files/   # Document management
│   │   │   ├── create/route.js
│   │   │   ├── get_documents/route.js
│   │   │   ├── save/route.js
│   │   │   ├── delete/route.js
│   │   │   └── export/route.js
│   │   └── generate_data/  # AI features
│   ├── editor/             # Document editor
│   └── ui/                 # Reusable components
│       ├── button.jsx
│       ├── dashboard/page.js
│       ├── login/page.js
│       └── register/page.js
├── utils/                  # Utility functions
│   ├── auth.js            # Authentication utilities
│   ├── db.js              # Database connection
│   ├── converter.js       # File conversion
│   └── gcs.js             # Cloud storage
└── test/                   # Testing infrastructure
    ├── setup.js           # Test configuration
    ├── utils.js           # Test utilities
    └── integration/       # Integration tests

Key Files to Understand¶

`src/utils/auth.js`¶

Authentication utilities including: - Password hashing/verification - JWT token generation/validation - Authenticated request wrapper

`src/utils/db.js`¶

Database connection and utilities: - MongoDB client configuration - Connection pooling - Database error handling

`src/app/api/` Routes¶

RESTful API endpoints: - Authentication flow - Document CRUD operations - File upload/download - Export functionality

Testing Your Setup¶

1. Run All Tests¶

npm run test:run

Expected output:

✓ 62 tests passing
✓ 0 tests failing
✓ Test files: 7
✓ Coverage: High coverage across components

2. Test API Endpoints¶

Using curl or a tool like Postman:

# Health check
curl http://localhost:3000/api/healthz

# Should return: {"status": "ok"}

3. Test Frontend¶

Navigate to http://localhost:3000
Register a new account
Login with your credentials
Access the dashboard

Common Development Issues¶

Port Already in Use¶

# Error: Port 3000 is already in use
# Solution: Kill the process or use different port
lsof -ti:3000 | xargs kill -9
# OR
npm run dev -- --port 3001

MongoDB Connection Issues¶

# Error: MongoNetworkError
# Check if MongoDB is running:
brew services start mongodb-community
# Or check connection string in .env

Missing Dependencies¶

# Error: Module not found
# Solution: Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Test Failures¶

# Run tests with verbose output
npm run test -- --verbose

# Run specific failing test
npm run test -- --grep "failing test name"

Development Tools¶

Recommended VS Code Extensions¶

ES7+ React/Redux/React-Native snippets
Auto Rename Tag
Prettier - Code formatter
GitLens
Thunder Client (for API testing)

Browser Dev Tools¶

React Developer Tools
Redux DevTools (if using Redux)
Network tab for API debugging
Console for JavaScript debugging

Environment Specific Notes¶

macOS Setup¶

# Install Node.js via Homebrew
brew install node

# Install MongoDB
brew install mongodb-community
brew services start mongodb-community

Windows Setup¶

# Install Node.js from nodejs.org
# Install MongoDB Community Server
# Use Git Bash for commands

Linux (Ubuntu) Setup¶

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install MongoDB
sudo apt install mongodb