LMS Documentation

Appearance

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 - JavaScript runtime (v1.3.1)
  • PostgreSQL - Database (v14 or higher)
  • Git - Version control

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

Run migrations (if applicable):

bash
cd apps/client-backend
pnpm run typeorm migration:run

Development ​

Starting All Services ​

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

bash
pnpm dev

This will start:

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 ​

  1. Create or modify a controller in apps/client-backend/src/controllers/
  2. Add TSOA decorators for OpenAPI generation
  3. The OpenAPI spec and routes are auto-generated
  4. 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 ​

  1. Create entity in packages/db/src/entities/
  2. Extend from BaseEntity or implement entity interface
  3. Use TypeORM decorators
  4. 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 ​

  1. Create component in apps/client-frontend/src/components/
  2. Use TypeScript and React best practices
  3. Import types from @repo/api
  4. 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 ​

  1. Create function in apps/cloud-functions/src/functions/
  2. Register in src/router.ts
  3. 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:

Getting Help ​

If you encounter issues:

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