Getting Started

This guide will help you set up your development environment and start contributing to the LMS project.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js - Version 20 or higher (managed via .tool-versions)
pnpm - Package manager (v9 or higher recommended)
Bun - Used as alternative to tsx for running TypeScript files (v1.3.1 or higher)
PostgreSQL - Database (v14 or higher)
Git - Version control

Package Manager

This project uses pnpm as the primary package manager. Bun is only used as a TypeScript runner (like tsx), not for package management or test running.

Optional Tools

Docker - For containerized development
VS Code - Recommended IDE with extensions

Installation

1. Clone the Repository

bash

git clone https://github.com/RichDom2185/fyp.git
cd fyp

2. Install Dependencies

bash

pnpm install

This will install dependencies for all packages in the monorepo.

3. Set Up Environment Variables

Create .env files for the backend and cloud functions:

Backend Environment

Create apps/client-backend/.env:

env

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=your_db_user
DATABASE_PASSWORD=your_db_password
DATABASE_NAME=lms_dev

# JWT
JWT_SECRET=your_jwt_secret_key

# Firebase (if using)
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_PRIVATE_KEY=your_private_key
FIREBASE_CLIENT_EMAIL=your_client_email

# Appwrite (if using)
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=your_project_id
APPWRITE_API_KEY=your_api_key

# OpenAI (if using AI features)
OPENAI_API_KEY=your_openai_api_key

# Server
PORT=3000
NODE_ENV=development

Cloud Functions Environment

Create apps/cloud-functions/.dev.vars:

env

JWT_SECRET=your_jwt_secret_key
# Add other cloud function specific variables

4. Set Up Database

Create a PostgreSQL database:

bash

createdb lms_dev

INFO

The application uses TypeORM with automatic schema synchronization in development. Database migrations are managed through TypeORM but are not yet exposed as package.json scripts.

Development

Starting All Services

From the root directory, start all services in development mode:

bash

pnpm dev

This will start:

Frontend dev server (http://localhost:5173)
Backend API server (http://localhost:3000)
API type generation (watches for changes)
Cloud functions dev server

Starting Individual Services

You can also start services individually:

Frontend Only

bash

cd apps/client-frontend
pnpm dev

Backend Only

bash

cd apps/client-backend
pnpm dev

Cloud Functions Only

bash

cd apps/cloud-functions
pnpm dev

Documentation Site Only

bash

cd apps/docs
pnpm dev

Project Structure

fyp/
├── apps/
│   ├── client-frontend/
│   │   ├── src/
│   │   │   ├── components/    # React components
│   │   │   ├── pages/         # Page components
│   │   │   ├── hooks/         # Custom React hooks
│   │   │   ├── queries/       # TanStack Query hooks
│   │   │   ├── redux/         # Redux store
│   │   │   ├── routes/        # Route definitions
│   │   │   └── utilities/     # Frontend utilities
│   │   ├── vite.config.ts
│   │   └── package.json
│   │
│   ├── client-backend/
│   │   ├── src/
│   │   │   ├── controllers/   # API controllers
│   │   │   ├── services/      # Business logic
│   │   │   ├── integrations/  # External service integrations
│   │   │   ├── gateways/      # Gateway services
│   │   │   └── internal/      # Internal utilities
│   │   ├── lib/              # Generated files (routes, types)
│   │   └── package.json
│   │
│   ├── cloud-functions/
│   │   ├── src/
│   │   │   ├── functions/    # Individual functions
│   │   │   ├── middleware/   # Middleware
│   │   │   └── utils/        # Utilities
│   │   └── wrangler.toml     # Cloudflare config
│   │
│   └── docs/                 # This documentation site
│
├── packages/
│   ├── api/                  # Generated API client
│   ├── db/                   # Database entities
│   ├── utils/                # Shared utilities
│   ├── translations/         # i18n files
│   └── vite-plugin-i18n-types/  # i18n plugin
│
└── deployment/               # Deployment configs

Development Workflow

1. Make Changes

Edit files in your preferred editor. The dev servers will automatically reload.

2. Type Generation

When you modify backend controllers:

TSOA automatically regenerates the OpenAPI spec
The API package regenerates TypeScript types
Frontend gets updated type definitions

3. Run Tests

bash

# Run all tests
pnpm test

# Run tests for a specific package
cd apps/client-frontend
pnpm test

# Run tests in watch mode
pnpm test:watch

# Generate coverage report
pnpm coverage

4. Lint and Format

bash

# Lint all packages
pnpm lint

# Auto-fix linting issues
pnpm lint -- --fix

# Format code with Prettier
pnpm format

5. Build

bash

# Build all packages
pnpm build

# Build specific package
cd apps/client-frontend
pnpm build

IDE Setup

VS Code

Recommended extensions (defined in .vscode/extensions.json):

ESLint
Prettier
TypeScript and JavaScript Language Features
Tailwind CSS IntelliSense
GitLens
REST Client

The repository includes VS Code settings and code snippets for React and TypeORM.

Settings

The project includes .vscode/settings.json with:

Format on save enabled
ESLint auto-fix on save
TypeScript configuration
Recommended formatter settings

Common Tasks

Adding a New API Endpoint

Create or modify a controller in apps/client-backend/src/controllers/
Add TSOA decorators for OpenAPI generation
The OpenAPI spec and routes are auto-generated
Frontend types are automatically updated

Example:

typescript

@Route("api/courses")
export class CourseController extends Controller {
  @Get("{id}")
  public async getCourse(@Path() id: string): Promise<Course> {
    // Implementation
  }
}

Adding a Database Entity

Create entity in packages/db/src/entities/
Extend from BaseEntity or implement entity interface
Use TypeORM decorators
Export from packages/db/src/index.ts

Example:

typescript

@Entity()
export class Course {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  // ... other fields
}

Adding a Frontend Component

Create component in apps/client-frontend/src/components/
Use TypeScript and React best practices
Import types from @repo/api
Use TanStack Query for data fetching

Example:

typescript

import { useQuery } from "@tanstack/react-query";
import { apiClient } from "@repo/api";

export function CourseList() {
  const { data, isLoading } = useQuery({
    queryKey: ["courses"],
    queryFn: () => apiClient.GET("/api/courses"),
  });

  // Component implementation
}

Adding a Cloud Function

Create function in apps/cloud-functions/src/functions/
Register in src/router.ts
Deploy to Cloudflare Workers

Example:

typescript

import { Hono } from "hono";

export const myFunction = new Hono();

myFunction.get("/endpoint", async (c) => {
  // Function implementation
  return c.json({ result: "success" });
});

Troubleshooting

Port Already in Use

If you get a port conflict:

bash

# Kill process on port 3000 (backend)
lsof -ti:3000 | xargs kill -9

# Kill process on port 5173 (frontend)
lsof -ti:5173 | xargs kill -9

Database Connection Issues

Verify PostgreSQL is running
Check database credentials in .env
Ensure database exists
Check network connectivity

Type Generation Not Working

bash

# Manually trigger API generation
cd packages/api
pnpm dev

# Manually trigger backend spec generation
cd apps/client-backend
pnpm dev:api

Build Failures

bash

# Clean all build artifacts
pnpm clean

# Reinstall dependencies
rm -rf node_modules
pnpm install

# Rebuild everything
pnpm build

Next Steps

Now that your environment is set up:

Architecture Overview - Understand the system design
AI Architecture - Learn about AI providers and tool calling
Frontend Guide - Build UI components
Backend Guide - Create API endpoints
Type Safety Flow - Learn about type generation

Getting Help

If you encounter issues:

Check this documentation
Review existing code examples
Check GitHub issues
Ask the development team

Getting Started ​

Prerequisites ​

Optional Tools ​

Installation ​

1. Clone the Repository ​

2. Install Dependencies ​

3. Set Up Environment Variables ​

Backend Environment ​

Cloud Functions Environment ​

4. Set Up Database ​

Development ​

Starting All Services ​

Starting Individual Services ​

Frontend Only ​

Backend Only ​

Cloud Functions Only ​

Documentation Site Only ​

Project Structure ​

Development Workflow ​

1. Make Changes ​

2. Type Generation ​

3. Run Tests ​

4. Lint and Format ​

5. Build ​

IDE Setup ​

VS Code ​

Settings ​

Common Tasks ​

Adding a New API Endpoint ​

Adding a Database Entity ​

Adding a Frontend Component ​

Adding a Cloud Function ​

Troubleshooting ​

Port Already in Use ​

Database Connection Issues ​

Type Generation Not Working ​

Build Failures ​

Next Steps ​

Getting Help ​

Getting Started

Prerequisites

Optional Tools

Installation

1. Clone the Repository

2. Install Dependencies

3. Set Up Environment Variables

Backend Environment

Cloud Functions Environment

4. Set Up Database

Development

Starting All Services

Starting Individual Services

Frontend Only

Backend Only

Cloud Functions Only

Documentation Site Only

Project Structure

Development Workflow

1. Make Changes

2. Type Generation

3. Run Tests

4. Lint and Format

5. Build

IDE Setup

VS Code

Settings

Common Tasks

Adding a New API Endpoint

Adding a Database Entity

Adding a Frontend Component

Adding a Cloud Function

Troubleshooting

Port Already in Use

Database Connection Issues

Type Generation Not Working

Build Failures

Next Steps

Getting Help