Contribution Guide

Contribution Guide

Table of Contents

• Prerequired
• Getting Started
  • Web
  • API
  • Scraper
  • Computation
  • Admin
• Generate new Application
• Git Commit Guideline
• Project Structure
  • App
  • Libs
  • Tools
• To-be Dependency Graph (WIP)

Prerequired

โปรดติดตั้ง Tools ก่อน

• Git
• Node.js
• PNPM
• Docker

Getting Started

สำหรับผู็ที่ต้องการ contribute สามารถเริ่มได้จากการ clone repository ก่อน เพื่อรับ Source Code ทั้งหมดของ CU Get Reg Project

git clone https://github.com/thinc-org/cugetreg.git

ขอให้ทำการติดตั้ง node๋JS รุ่น LTS ล่าสุด

จากนั้นทำการ Install dependencies ด้วย PNPM

pnpm install

สำหรับ MacOS

ถ้าใครเจอ error เกี่ยวกับ canvas หรือ gyp ให้ run command ต่อไปนี้

brew install pkg-config cairo pango libpng jpeg giflib librsvg

How to run

ในการ Run Apps ต่างๆ เราจะใช้ Turbo เป็นเครื่องมือหลักในการจัดการ application หลาย ๆ อย่าง ทั้ง Frontend, Backend และอื่น ๆ

ขั้นแรกให้ทำการสร้างไฟล์ตั้งค่า (Dotenv File) ในแต่ละ Apps ที่จะใช้โดยตั้งชื่อไฟล์เป็น .env.local สามารถดูค่าที่ต้องใส่ได้ใน .env.template เช่น ถ้าจะรันแค่ Api App ก็ให้สร้างไฟล์ apps/api/.env.local ก่อน

จากนั้นให้รัน App โดยใช้คำสั่ง

pnpm dev --scope="<appname>"

โดย <appname> ที่ใช้ได้มีดังนี้

• web: Frontend สำหรับ CU Get Reg
• api: API Backend สำหรับ CU Get Reg
• reg-scraper: ตัวดึงข้อมูลจาก Reg Chula
• admin-web: Frontend ระบบ Backoffice
• admin-api: Backend ระบบ Backoffice

โดย Web Application (web) เมื่อรันแล้วจะสามารถเข้าถึงได้ผ่าน Browser โดยใช้ URL localhost:4200 ส่วน Backend Application (api) จะเป็น http://localhost:3333/_api

Section ทั้งหมดต่อไปนี้ outdate แล้ว

Web

Service สำหรับ serve หน้าเว็บหลักให้ผู้ใช้ทั่วไป

สำหรับ Frontend Web Developer, app หลักจะอยู่ใน apps/web สามารถเริ่ม run Application ด้วย

nx run web:serve

โดย Application จะรันบน localhost:4200

สามรถรัน Test ด้วยคำสั่ง

nx run web:test

และ Build Docker image โดยคำสั่ง

nx run web:docker-build

API

Service สำหรับ provide API ทั้ง course, review และ user

ก่อนอื่นตั้งค่า .env.local ก่อน

สำหรับ Backend Developer, app หลักจะอยู่ใน apps/api สามารถเริ่ม run Application ด้วย

nx run api:serve

โดย Application จะรันบน localhost:3333

สามรถรัน Test ด้วยคำสั่ง

nx run api:test

และ Build Docker image โดยคำสั่ง

nx run api:docker-build

Scraper

Service สำหรับดึงข้อมูลจาก Reg Chula ด้วยวิธีการ scrape

เร็ว ๆ นี้

Computation

Service สำหรับการคำนวณระบบ Recommendation

เร็ว ๆ นี้

Admin

Service ที่ใช้สำหรับผู้ดูแลระบบเบื้องหลัง

เร็ว ๆ นี้

Generate new Application

เราสามารถใช้ Office Nx Package ในการ Generate Application ได้

• NestJS: https://nx.dev/packages/nest
• NextJS https://nx.dev/packages/next
• AngularJS: https://nx.dev/packages/angular

Git Commit Guideline

เร็ว ๆ นี้

Project Structure

จะอธิบาย structure ของ project โดยสังเขป

workspace
├── apps
│   ├── api
│   ├── web
|   ├── web-e2e (not implemented)
│   ├── scraper (planned)
│   ├── computation (planned)
│   └── admin-web (planned)
├── libs
|   ├── codegen
|   ├── course-utils
│   └── react-ui (coming soon)
└── tools

App

จะเป็นที่ที่เอาไว้รวม source code ส่วนที่เป็น application ทั้งหมดของ CU Get Reg ได้แก่

1. web เป็น service ที่ใช้สำหรับ serve หน้าเว็บให้ผู้ใช้ทั่วไป
2. web-e2e เป็น code สำหรับทำ E2E Test ซึ่งตอนนี้ยังไม่ได้ implement
3. api เป็น service ที่ใช้สำหรับ provide API ทั้ง course, review และ user
4. scraper เป็น service ที่ใช้สำหรับดึงข้อมูลจาก Reg Chula ด้วยวิธีการ scrape
5. computation เป็น service ที่ใช้สำหรับ การคำนวณระบบ Recommendation
6. admin-web เป็น service ที่ใช้สำหรับผู้ดูแลระบบเบื้องหลัง

Libs

Library ควรเป็นที่ที่มี Test Coverage 80% ขึ้นไป

จะเป็น source code ของส่วนที่เป็น library ที่สามารถแชร์ระหว่าง Application ได้

1. codegen เป็น library ที่ใช้ในการ generate type เพื่อให้ frontend (apps/web) สามารถใช้งาน GraphQL ได้โดย type safe
2. course-utils เป็น library ที่ใช้สำหรับเก็บรวมรวบ utils ที่เกียวกับ course เช่นข้อมูลคณะ type ต่าง ๆ
3. react-ui เป็น library ที่ใช้สำหรับการจัดการ UI ของ CU Get Reg Web ซึ่งใช้ Material UI v5 เป็นหลัก

ทั้งนี้ในส่วนของ UI เหตุผลที่ต้องแยกออกเป็น library เพื่อทำ shared ui ระหว่าง application และยังสามารถ clone ui library ใหม่ที่ใช้ ui library อื่นเป็นหลักแทนได้เช่น Tailwind

Tools

จะเป็นส่วนที่เอาไป define Workspace custom CLI สำหรับทำอะไรบางอย่าง

To-be Dependency Graph (WIP)

ใน Monorepo CU Get Reg นี้ สิ่งที่คาดหวังให้เป็นจะมีภาพประมาณนี้ (สามารแก้ไขทีหลังได้)

flowchart TD
    codegen --> web
    api -.-> codegen
    codegen --> scraper
    codegen --> admin-web
    course-utils --> web
    course-utils --> scraper
    course-utils --> admin-web
    material-ui -.-> react-ui
    react-ui --> web
    react-ui --> admin-web
    computation

Loading

computation เขียนด้วยภาษา Python จึงไม่สามารถแชร์อะไรได้

react-ui จะ import จาก material ui อีกที ซึ่งทำหน้าที่เป็น UI Adaptor หากในอนาคตไม่อยากใช้ material ui แล้ว แทนที่จะไปไล่แก้ทั้ง Applications ให้มาแก้ที่ react-mui-ui แทน