Visionary Education Foundation Mentorship Web App

https://github.com/yuanjian-org/app
Admin
A web application supporting mentorship programs at Visionary Education Foundation, developed by VEF...
Tokens:3,896
Snippets:21
Trust Score:3.2
License:AGPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Configure Project Preparation and Git Hooks

Source: https://github.com/yuanjian-org/app/blob/main/docs/package.json.md

The `yarn prepare` command runs during local installation (e.g., `yarn install` or `npm install`), setting up project-specific configurations. As part of this, `husky install` is executed to enable Git hooks, ensuring pre-commit or pre-push scripts are active as per Husky's official documentation.

```Shell
yarn prepare
```

```Shell
husky install
```

--------------------------------

### Build Docker Image

Source: https://github.com/yuanjian-org/app/blob/main/docs/Deployment.md

This snippet shows the command to build the Docker image for the application. Ensure the .env file is correctly configured before running this command.

```Shell
docker compose build
```

--------------------------------

### Install OR-Tools Library

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Installs the `ortools` library using pip, which is a crucial dependency for the optimization solver utilized in the mentee-mentor matching algorithm. This step ensures all necessary components are available.

```Shell
!pip3 install ortools
```

--------------------------------

### Robots.txt Allowing All Crawlers

Source: https://github.com/yuanjian-org/app/blob/main/public/robots.txt

This robots.txt configuration allows all web crawlers (specified by 'User-Agent: *') to access all content on the website. The 'Disallow:' directive with an empty path indicates no restrictions, effectively allowing everything.

```Robots.txt
User-Agent: *
Disallow:
```

--------------------------------

### Set Docker Application Image Name

Source: https://github.com/yuanjian-org/app/blob/main/docs/Deployment.md

This snippet illustrates how to set the application's Docker image name within the .env file, which is required for Docker deployment.

```Configuration
APP_DOCKER_IMAGE=<app_image_name>
```

--------------------------------

### Run Unit Tests with Yarn

Source: https://github.com/yuanjian-org/app/blob/main/docs/package.json.md

This command executes all configured unit tests for the project. It is typically defined in the `scripts` section of `package.json` and can be run from the command line.

```Shell
yarn test
```

--------------------------------

### Configure Environment Variables for Local Development

Source: https://github.com/yuanjian-org/app/blob/main/README.md

Instructions to create a `.env` file in the repository root with essential environment variables for local development, including `DATABASE_URI` and `NEXTAUTH_SECRET`. This configures database connection and authentication for the application.

```Shell
DATABASE_URI=postgres://localhost/yuanjian
NEXTAUTH_SECRET=123
```

--------------------------------

### Open Cypress Interactive Test Runner

Source: https://github.com/yuanjian-org/app/blob/main/cypress/README.md

Execute this command to launch the Cypress interactive test runner, which opens a browser-based launchpad. From the launchpad, users can select specific E2E test specifications to run and debug interactively.

```shell
yarn cypress-open
```

--------------------------------

### Matching Algorithm Configuration Parameters

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Defines global configuration parameters for the mentee-mentor matching algorithm, including flags for initial vs. final matching, data normalization settings, score cutoffs, mentor/mentee capacity bounds, and file paths for input data. These parameters control the behavior and constraints of the matching process.

```Python
import dataclasses
from typing import Dict, Mapping, Sequence, Tuple

import pandas as pd
import numpy as np
import numpy.ma as ma

# Whether to solve for initial matching 初配 or final matching 定配.
INIITIAL_MATCH = False

# If true, remove mean and stdev.
_NORMALIZE_DATA = True if INIITIAL_MATCH else False

# The two parameters below are valid only when _NORMALIZE_DATA is True. 
# 
# If true, when normalizing, ignore the highest scores when computing the
# statistics and leave these scores unmodified.
_IGNORE_HIGHEST_SCORES = True
_HIGHEST_SCORE_CUTOFF = 50

# If true, for a mentee, among the mentors with scores higher than this,
# one of the mentors must be included in the matched pool.
MUST_MATCH_HIGHEST_SCORES = True if INIITIAL_MATCH else False
MUST_MATCH_SCORE_CUTOFF = _HIGHEST_SCORE_CUTOFF

# Key: Mentor capacity for final-matched mentees, Value: Mentor capacity for
# chat slots.
MENTOR_CAPACITY_UPPER_BOUND: Mapping[int, int] = {
  1: 4,
  2: 4,
  3: 5,
  0: 2, # for dummy mentors
} if INIITIAL_MATCH else {
  1: 1,
  2: 2,
  3: 3,
  0: 2,
}

MENTEE_DEMAND_UPPER_BOUND = 3 if INIITIAL_MATCH else 1
MENTEE_DEMAND_LOWER_BOUND = 3 if INIITIAL_MATCH else 1

# Must be the same as bannedScore in src/api/routes/match.ts
BANNED_SCORE = -10

# Higher offset encourages more matches. Setting to -10, for example,
# matches as few pairs as possible as long as the constraints are satisfied.
# This is the regularization term.
_SCORE_OBJ_OFFSET = 0.0

# The pwd in Google Colab is `/content`.
_SCORES_FILENAME = 'matching_scores_with_dummy.csv'
_CAPACITY_FILENAME = 'mentor_capacities_with_dummy.csv'
_CAPACITY_COLUMN_NAME = '学生容量'
```

--------------------------------

### Matching Algorithm Output Format

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Illustrates the expected output format of the matching algorithm, showing assigned mentees for each mentor and assigned mentors for each mentee. This format provides a clear overview of the successful pairings.

```Text
  mentor=MentorM,assigned_mentees=MenteeE,MenteeF, ...
  mentor=MentorN,assigned_mentees=MenteeF, ...
  mentee=MenteeE,assigned_mentors=MentorM, ...
  mentor=MenteeF,assigned_mentors=MenteeM,MentorN ...
```

--------------------------------

### Execute and Interpret CP-SAT Assignment Solution

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

This snippet demonstrates how to use the `ModelAssignment` and `SolveAssignment` functions to solve a concrete assignment problem. It then prints solver statistics such as status, conflicts, branches, and wall time. Finally, it iterates through the decision variables to extract and display the actual mentor-mentee assignments in a human-readable format and a machine-friendly CSV-like format.

```python
# Create a constraint programming problem.
model, pair_to_var = ModelAssignment(
    mentors=mentors, mentees=mentees, scores=scores)
# Solve the problem.
solver, status_name = SolveAssignment(model=model)
# Print the solution.
print('\nStatistics')
print(f'  status   : {status_name}')
print(f'  conflicts: {solver.NumConflicts()}')
print(f'  branches : {solver.NumBranches()}')
print(f'  wall time: {solver.WallTime()} s')

if status_name != 'FEASIBLE' and status_name != 'OPTIMAL':
  raise ValueError(f'Unexpected: Solver state is {status_name}')
  
mentor_view: Mapping[int, Sequence[int]] = {mentor: [] for mentor in mentors}
mentee_view: Mapping[int, Sequence[int]] = {mentee: [] for mentee in mentees}
for pair, var in pair_to_var.items():
  assign_decision = solver.Value(var)
  if assign_decision == 1:
    mentor_view[pair.mentor].append(pair.mentee)
    mentee_view[pair.mentee].append(pair.mentor)
print("\n### Mentor => Mentees\n")
for mentor, assigned_mentees in mentor_view.items():
  print(
      f"{_MENTOR_ID_TO_NAME[mentor]} => "
      f"{[_MENTEE_ID_TO_NAME[mentee] for mentee in assigned_mentees]}")
print("\n### Mentee => Mentors\n")
for mentee, assigned_mentors in mentee_view.items():
  print(
      f"{_MENTEE_ID_TO_NAME[mentee]} => "
      f"{[_MENTOR_ID_TO_NAME[mentor] for mentor in assigned_mentors]}")
print("\n### Mentee,Mentor... (machine friendly)\n")
for mentee, assigned_mentors in mentee_view.items():
  print(
      f"{_MENTEE_ID_TO_NAME[mentee]},"
      f"{','.join([_MENTOR_ID_TO_NAME[mentor] for mentor in assigned_mentors])}")
```

--------------------------------

### Define CP-SAT Model and Solver for Assignment

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

This Python code defines two core functions for an assignment problem: `ModelAssignment` and `SolveAssignment`. `ModelAssignment` constructs a CP-SAT model, including binary decision variables for mentor-mentee pairs, capacity constraints for mentors, demand constraints for mentees, and an objective to maximize scores. `SolveAssignment` initializes and runs the CP-SAT solver on the created model, setting a time limit and returning the solver object and status.

```python
from ortools.sat.python import cp_model


def ModelAssignment(
    mentors: Sequence[int],
    mentees: Sequence[int],
    scores: Mapping[Pair, float]
) -> Tuple[cp_model.CpModel, Mapping[Pair, cp_model.IntVar]]:
  """Models assignment problem and returns model and decision variables."""
  # Create the model.
  model = cp_model.CpModel()

  # Create the variables.
  pair_to_var: Mapping[Pair, cp_model.IntVar] = {}
  for pair, score in scores.items():
    # Binary decision variables, 1 if mentor is matched with mentee.
    upper_bound = 1 if scores[pair] != BANNED_SCORE else 0
    var = model.NewIntVar(
        0, upper_bound, f'mentor_{pair.mentor}_mentee_{pair.mentee}')
    pair_to_var[pair] = var

  # Create the constraints.
  mentor_to_vars: Mapping[int, Sequence[cp_model.IntVar]] = {
      mentor: [] for mentor in mentors}
  mentee_to_vars: Mapping[int, Sequence[cp_model.IntVar]] = {
      mentee: [] for mentee in mentees}
  mentee_to_must_match: Mapping[int, Sequence[cp_model.IntVar]] = {
      mentee: [] for mentee in mentees}
  for pair, var in pair_to_var.items():
    mentor_to_vars[pair.mentor].append(var)
    mentee_to_vars[pair.mentee].append(var)
    if MUST_MATCH_HIGHEST_SCORES and scores[pair] >= MUST_MATCH_SCORE_CUTOFF:
      mentee_to_must_match[pair.mentee].append(var)
  # Mentor capacity constraint: Every mentor paired with <= UB mentees.
  # Key: mentor ID. Value: all variables that contains to mentor ID.
  for mentor, vars in mentor_to_vars.items():
    capacity = MENTOR_CAPACITY_UPPER_BOUND.get(mentor_id_to_capacity[mentor])
    if capacity is None:
      raise ValueError(f"MENTOR_CAPACITY_UPPER_BOUND not "
                       f"found for {mentor_id_to_capacity[mentor]}")
    model.Add(sum(vars) <= capacity)
  # Mentee demand constraint: Every mentee paired with >= LB mentors
  # and <= UB mentors.
  # Key: mentor ID. Value: all variables that contains to mentor ID.
  for mentee, vars in mentee_to_vars.items():
    model.Add(sum(vars) >= MENTEE_DEMAND_LOWER_BOUND)
    model.Add(sum(vars) <= MENTEE_DEMAND_UPPER_BOUND)
  # For a mentee, among the mentors with scores higher than this,
  # one of the mentors must be included in the matched pool.
  for mentee, vars in mentee_to_must_match.items():
    if vars:
      model.Add(sum(vars) >= 1)

  # Create the objective.
  var_to_score = [(pair_to_var[pair], score + _SCORE_OBJ_OFFSET) for pair, score in scores.items()]
  objective_vars, objective_coefficients = zip(*var_to_score)
  model.Maximize(cp_model.LinearExpr.WeightedSum(
      expressions=objective_vars, coefficients=objective_coefficients))

  return model, pair_to_var

def SolveAssignment(model: cp_model.CpModel) -> Tuple[cp_model.CpSolver, str]:
  """Solves assignment problem."""
  # Creates a solver and solves the model.
  solver = cp_model.CpSolver()
  solver.parameters.random_seed = 123

  # Sets a time limit of 10 seconds.
  solver.parameters.max_time_in_seconds = 10.0

  status = solver.Solve(model)
  status_name = solver.StatusName(status)
  if status != cp_model.OPTIMAL:
    print(f"Non optimal solver status: {status_name=}")
  return solver, status_name
```

--------------------------------

### Load Mentor Capacities

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Reads mentor capacity data from the configured CSV file into a pandas DataFrame. It then iterates through mentors to populate a dictionary mapping each mentor's ID to their specified maximum mentee capacity, ensuring capacity constraints are available for the matching process.

```Python
capacity_df: pd.DataFrame = pd.read_csv(_CAPACITY_FILENAME, index_col='导师')

mentor_id_to_capacity: Dict[str, int] = {}
for mentor, mentor_name in zip(mentors, mentor_names):
  mentor_id_to_capacity[mentor] = capacity_df.loc[mentor_name][_CAPACITY_COLUMN_NAME]
  print(f'{mentor_name=}, capacity={mentor_id_to_capacity[mentor]}')
```

--------------------------------

### Mentor Capacity Input Format

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Specifies the format for the `mentor_capacities_with_dummy.csv` file, detailing the maximum number of mentees each mentor is willing to take. Only the '导师' (mentor) and '学生容量' (capacity) columns are considered.

```CSV
  导师,学生容量
  MentorM,2
  MentorN,4
  Dummy,3
```

--------------------------------

### Visualize Allowed Code Dependencies

Source: https://github.com/yuanjian-org/app/blob/main/README.md

A Mermaid graph illustrating the allowed dependency flow between different source code directories (`src`, `src/api`, `src/shared`) to enforce security and programming rules configured by ESLint. This ensures a structured and maintainable codebase.

```Mermaid
graph TD;
    src[the rest of src]-->|ok|src/shared;
    src/api-->|ok|src/shared;
```

--------------------------------

### Load and Preprocess Mentee-Mentor Scores

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Loads mentee preference scores from the configured CSV file into a pandas DataFrame, extracts mentor and mentee names, and converts scores into a NumPy array. Optionally normalizes scores by removing mean and standard deviation, handling masked values and banned scores to prepare data for the matching algorithm.

```Python
scores_df: pd.DataFrame = pd.read_csv(_SCORES_FILENAME, index_col=0)

mentors, mentor_names = zip(*enumerate(scores_df.columns.to_list()))
mentees, mentee_names = zip(*enumerate(scores_df.index.to_list()))
_MENTOR_ID_TO_NAME: Mapping[int, str] = {j: name for j, name in zip(mentors, mentor_names)}
_MENTEE_ID_TO_NAME: Mapping[int, str] = {i: name for i, name in zip(mentees, mentee_names)}

@dataclasses.dataclass(order=False, frozen=True)
class Pair:
  """Pair of mentor, mentee."""
  mentor: int
  mentee: int

scores_matrix: np.ndarray = scores_df.to_numpy(dtype=float)
if _NORMALIZE_DATA:
  if _IGNORE_HIGHEST_SCORES:
    scores_matrix_ma = ma.masked_where(
        (scores_matrix >= _HIGHEST_SCORE_CUTOFF) | (scores_matrix == BANNED_SCORE),
        scores_matrix, copy=False)
  else:
    scores_matrix_ma = ma.masked_where(
        scores_matrix == BANNED_SCORE, scores_matrix, copy=False)
  scores_matrix_ma -= scores_matrix_ma.mean(axis=1, keepdims=True)
  scores_matrix_ma /= scores_matrix_ma.std(axis=1, ddof=1, keepdims=True)
  scores_matrix = np.nan_to_num(scores_matrix)  # replace nan with 0
scores: Dict[Pair, float] = {
    Pair(mentee=i, mentor=j): scores_matrix[i][j]
    for i in range(len(mentees)) for j in range(len(mentors))}

print(f"mentors={mentor_names}")
print(f"mentees={mentee_names}")
if _NORMALIZE_DATA:
  print(f"###### NORMALIZED_SCORES ######\n{scores_matrix}")
print("###### SCORES TABLE ######")
scores_df
```

--------------------------------

### Mentee Preference Score Matrix Input Format

Source: https://github.com/yuanjian-org/app/blob/main/tools/match.ipynb

Defines the structure for the `matching_scores_with_dummy.csv` file, which contains mentee preference scores for mentors. Scores range from -5 (least preferred) to 5 (most preferred), with a 'Dummy' mentor column for cases where mentor supply is lower than demand.

```CSV
  mentee,MentorM,MentorN, ... ,Dummy
  MenteeE,0,-5, ... ,0
  MenteeF,2,4, ... ,0
```

--------------------------------

### Check Vercel Production Environment

Source: https://github.com/yuanjian-org/app/blob/main/docs/package.json.md

This shell statement checks if the application is deployed in a Vercel production environment. It's often used in `package.json` scripts to conditionally run commands, such as database migrations, only during production deployments.

```Shell
if [ \"$VERCEL_ENV\" = \"production\" ]
```

--------------------------------

### Fix '$VERCEL_ENV' Unexpected Error on Windows

Source: https://github.com/yuanjian-org/app/blob/main/docs/package.json.md

This error on Windows, `"$VERCEL_ENV" was unexpected`, typically occurs when shell syntax for conditional execution (`&& if [...]`) is not correctly parsed. The fix involves removing the problematic conditional statement that attempts to run `ts-node tools/migrateDatabase.ts` based on the Vercel environment.

```Shell
&& if [ \"$VERCEL_ENV\" = \"production\" ]; then ts-node tools/migrateDatabase.ts; fi
```

--------------------------------

### Run All Cypress E2E Tests in Background

Source: https://github.com/yuanjian-org/app/blob/main/cypress/README.md

Use this command to run all Cypress E2E tests non-interactively from the command line. This mode is suitable for CI/CD pipelines and automatically captures screenshots and screencasts of test failures or specific test steps.

```shell
yarn cypress-run
```

--------------------------------

### Resolve 'TS_NODE_PROJECT' Error on Windows

Source: https://github.com/yuanjian-org/app/blob/main/docs/package.json.md

On Windows, the error `'TS_NODE_PROJECT' is not recognized as an internal or external command` indicates an issue with environment variable parsing. Adding `cross-env` before the `TS_NODE_PROJECT` assignment resolves this by providing a cross-platform way to set environment variables.

```Shell
cross-env TS_NODE_PROJECT=...
```
Tokens:
Raw