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

• Git
• Node.js v16
• PNPM
• Docker

Getting Started

สำหรับผู็ที่ต้องการ contribute สามารถเริ่มได้จากการ clone repository ก่อน

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

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

pnpm install

เพื่อให้เกิดปัญหาน้อยที่สุด แนะนำให้ใช้ node 16 LTS (lts/gallium)

สำหรับ MacOS

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

brew install pkg-config cairo pango libpng jpeg giflib librsvg

How to run

ใน Project นี้เราได้ใช้ Nx เป็นเครื่องมือหลักในการจัดการ application หลาย ๆ อย่าง ทั้ง Frontend, Backend และอื่น ๆ

ในแต่ละ apps ให้ทำการสร้าง .env.local ก่อน โดยดูสิ่งที่ต้องใส่ได้จาก .env.template

ถ้าต้องการ run ทุก Application ใน Workspace สามารถทำได้โดยคำสั่ง

nx run-many --target=serve --parallel

โดย Web Application จะรันบน localhost:4200 และ Backend Application จะรันบน localhost:3333

และถ้าต้องการ Build Docker image สามารถทำได้ด้วยคำสั่ง

nx run-many --target=docker-build --parallel

นอกจากนี้ Nx ยังมี command อื่น ๆ ให้เลือกใช้อีกมาก สามารถศึกษาเพิ่มเติมได้จาก Nx Commands

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 แทน