Skip to content

Latest commit

 

History

History
237 lines (140 loc) · 14.9 KB

README.md

File metadata and controls

237 lines (140 loc) · 14.9 KB
Raw

Connect

You'll find two sister products in this repository:

Both are created, run and managed by ReDI School of Digital Integration. We're a non-profit school in Germany (in Berlin, Hamburg, Munich and NRW) with a community of hundreds of professionals from the digital industry volunteering to teach and mentor students. Our students are tech-interested locals and newcomers to Germany.

Getting started for designers

See the Onboarding Checklist and Workflow for design tasks in our Wiki.

Getting started for developers

First of all, ReDI Connect and ReDI Talent Pool connect to a Salesforce instance via the NestJS API app. You'll need to set a number of environment variables in your .env and .env.development files to make various connections and features work. Reach out to @helloanil, @katamatata or @ericbolikowski to get set up.

After you've set up .env, make sure to update NX_DEV_MODE_EMAIL_RECIPIENT to your own email address to receive emails from the platform.

  1. Make sure you're running the v20 version of Node locally. To do this, you can install nvm, which allows you to select different versions of Node via the command line. Alternatively, we have added support for Volta. So, if you choose, you can use Volta, which sets project-defined tools automatically.
  2. We are using yarn as a package manager in our repository. If you don't have it on your machine yet, install it.
  3. Go to the root folder and run yarn to install the project dependencies (node_modules).
  4. Run yarn start:all to boot all apps, or a subset of apps using the start:x commands listed in the package.json file.
  5. Read the Onboarding Checklist in our Wiki.

You can open these in your browser:

  1. If you're using VS Code, make sure you:

    • Enable file nesting (setting explorer.fileNesting.enabled) to collapse React component .graphql, .generated.ts and .scss files. This makes it easier to use the file explorer.
    • Install the Run on Save extension to automatically generate react-query hooks when saving .graphql files. This will speed up your development so you don't need to manually run yarn graphql:codegen.

We use Nx Dev Tools to manage this monorepo. Find all the apps/products under apps/ and all libraries they consume under libs/.

Use trunk-based branching: create feature/bugfix/docs/refactor/blabla branches directly off master and file PRs to merge back into master. Name branches <type>/short-hyphenated-title, where type is feat, fix, docs, style, refactor, test or chore.

Note on how to use the GraphiQL playground

The GraphiQL playground is a tool that allows you to test the GraphQL API. It is available at http://localhost:3333/graphql.

The playground is a great tool to test the API, but it is not meant to be used in production. It is a development tool only.

Use it to view all the available GraphQL queries and mutations. Most queries and mutations require authentication. To authenticate, you need to provide a valid JWT token. You can get a valid JWT token by logging in to the ReDI Connect application. Use your browser's developer tools to view network requests. Once you are logged in, find the POST /api/redUsers/login request. There, copy the jwtToken. Then, in the GraphiQL playground, click on the HTTP HEADERS tab. Paste the following:

{
  "Authorization": "Bearer <your-jwt-token>"
}

Alternatively, use Loopback's Swagger (http://localhost:3003) to manually send a login request, and copy the JWT token from the response.

See this Loom video for a demo: https://www.loom.com/share/b2328a7ec6054afebb8249ea59ef2f18

More about GraphQL & data models

Code generation

We use GraphQL code generation to generate/update react-query hooks (queries and mutations). To enable code generation after changing NestJS entity models or any .graphql file, first, ensure the NestJS API is running, then execute yarn graphql:codegen.

To automatize the codegen after changes to .graphql files, install this VS Code “Run on Save” extension. The repository’s VS Code config (in .vscode/settings.json) is already set up to enable this.

Note: If code generation doesn’t work, it might be because the NestJS API app is not running. Make sure that it is in a running state.

Visualize the entire GraphQL schema

  1. Copy the contents of schema.graphql in the project root folder. If you want to ensure it’s 100% up to date, first start NestJS API (yarn start:alone:nestjs-api), then run yarn graphql:codegen
  2. Open GraphQL Voyager: https://ivangoncharov.github.io/graphql-voyager/
  3. Click Change Schema > SDL > paste the file in > Display.

Where and how are data model schemas defined?

Schemas for data models (e.g. ConProfile, ConMentoringSession, TpJobseekerProfile and TpJobListing) are defined in two places:

  1. Visually, in Salesforce: Salesforce provides an Object Manager to set up Objects and their properties (e.g. firstName, birthDate, etc.), through a web admin interface. Talk to Eric/Anil/Manu for access.
  2. In code, in the common-types library: see the repository folder libs/common-types/src/lib

Each data model in the common-types folder is represented by a TypeScript class. Every data model has two representations:

  1. As represented in the salesforce domain: when the file name or class name ends with Record, the model’s structure, property names and property types reflect how the data model is. The term Record is chosen since it’s standard terminology in Salesforce. Record is just Salesforce’s way of saying row or instance.
  2. As represented in the core domain: when the file name or class name ends with Entity, the model follows a simpler and flatter structure, the same one that was used for years before CON and TP data were migrated to Salesforce. We use the term Entity as it implies a “thing”, such as a jobseeker’s profile, a mentor<>mentee match, a logged mentoring session, and so forth.

There are two important reasons why data models have two representations:

  1. Salesforce enforces a certain complexity in its data models. For instance, the suffix __c is automatically added to the name of any property we define on a model/object. There are also nested objects within objects.
  2. For years, CON and TP data lived in a MongoDB database, with a simple and effective data model structure that suited our needs. After migrating all the data to Salesforce, we essentially had two choices: update all code to access data using Salesforce’s names for objects and properties, or create a wrapper / abstraction to maintain our “core” domain models as they’ve been. We chose the latter.

To convert data from one domain representation to another, we use Mapper classes. Look for file names ending in .mapper.

Our NestJS API thereafter uses GraphQL and code generation (codegen) to define types (both TS types and GraphQL object types) in various places. You can think of this as the data models “bubbling up” from the backend:

  1. All our data models, or entities, start in the libs/common-types/src/lib folder as TypeScript classes
  2. NestJS analyzes all classes with the decorator @ObjectType()
  3. NestJS generates a GraphQL schema, containing all our entities in the shape of object types
  4. The command yarn graphql:codegen uses the graphql-codegen tool to read the schema. It then generates Typescript types (see libs/data-access/src/lib/types/types.ts). It also scans all .graphql files for queries and mutations, and creates react-query queries and mutations stored in .generated.ts files right next to the .graphql file.

What responsibilities are still carried by Loopback?

  • Authenticate users
  • Store credentials in its linked MongoDB database
  • Create signed URLs for uploading assets to S3

Good to know

We integrated TailwindCSS into the redi-connect and redi-talent-pool applications to enhance styling capabilities and to enable a new UI components library - shadcn/ui.

A newly created shared-shadcn-ui-components library aims to replace Bulma in our codebase. Check the usage instructions for the shared-shadcn-ui-components library in this README file.

About the Nx monorepo

Main benefits:

  • code sharing between apps (NestJS backend, ReDI Connect, ReDI Talent Pool) - great for components, types, utilities, and much more
  • one linter to rule them all - no more crazy pull requests with style changes
  • one command to start it all - no more four terminal windows to start all the apps
  • overall easier to extend & scale - there’s future work in the pipeline for which Nx is a great match (Storybook, hint hint)

System Architecture

ReDI Connect and ReDI Talent Pool are two React front-ends that use a Express/Loopback/NodeJS back-end to access data stored in a MongoDB database. The backend is hosted on a virtual machine, whereas the React front-ends are compiled into static assets stored on AWS S3 / CloudFront. Emails to users are sent via AWS SES. Some other static assets plus user uploads are hosted in AWS S3 buckets.

This diagram shows the current system architecture of both platforms: Architecture

Production server administration

We use pm2 on the production servers to manage our two NodeJS servers - Loopback API and NestJS API.

  • Run pm2 monit for an overview of the two servers and their logs. Run pm2 status for a quick status of the servers.
  • NOTE: pm2 will automatically boot NestJS API and Loopback API on server restart.
  • To start/stop servers, run pm2 start <server-name> or pm2 stop <server-name>. To restart, run pm2 restart <server-name>. You don't need to include environment variables or various other flags, pm2 has this configuration "saved" since the first boot.

If you ever need to configure/start the servers from "scratch", here's how to do it:

  • [All the environment variables] pm2 restart --name loopback --log /home/ubuntu/loopback.log --max-memory-restart 250M /home/ubuntu/connect/apps/api/server/server.js
  • [All the environment variables] pm2 start --name nestjs-api --log /home/ubuntu/nestjs-api.log --max-memory-restart 500M connect/dist/apps/nestjs-api/main.js

If you need to update the environment variables, run the above command with restart instead of start, and also add the --update-env flag.

Nx out-of-the-box docs

All the below is written by Nx.

This project was generated using Nx.

🔎 Powerful, Extensible Dev Tools

Adding capabilities to your workspace

Nx supports many plugins which add capabilities for developing different types of applications and different tools.

These capabilities include generating applications, libraries, etc as well as the devtools to test, and build projects as well.

Below are our core plugins:

  • React
    • npm install --save-dev @nrwl/react
  • Web (no framework frontends)
    • npm install --save-dev @nrwl/web
  • Angular
    • npm install --save-dev @nrwl/angular
  • Nest
    • npm install --save-dev @nrwl/nest
  • Express
    • npm install --save-dev @nrwl/express
  • Node
    • npm install --save-dev @nrwl/node

There are also many community plugins you could add.

Generate an application

Run nx g @nrwl/react:app my-app to generate an application.

You can use any of the plugins above to generate applications as well.

When using Nx, you can create multiple applications and libraries in the same workspace.

Generate a library

Run nx g @nrwl/react:lib my-lib to generate a library.

You can also use any of the plugins above to generate libraries as well.

Libraries are shareable across libraries and applications. They can be imported from @talent-connect/mylib.

Development server

Run nx serve my-app for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding

Run nx g @nrwl/react:component my-component --project=my-app to generate a new component.

Build

Run nx build my-app to build the project. The build artifacts will be stored in the dist/ directory. Use the --prod flag for a production build.

Running unit tests

Run nx test my-app to execute the unit tests via Jest.

Run nx affected:test to execute the unit tests affected by a change.

Running end-to-end tests

Run ng e2e my-app to execute the end-to-end tests via Cypress.

Run nx affected:e2e to execute the end-to-end tests affected by a change.

Understand your workspace

Run nx dep-graph to see a diagram of the dependencies of your projects.

Further help

Visit the Nx Documentation to learn more.

☁ Nx Cloud

Computation Memoization in the Cloud

Nx Cloud pairs with Nx in order to enable you to build and test code more rapidly, by up to 10 times. Even teams that are new to Nx can connect to Nx Cloud and start saving time instantly.

Teams using Nx gain the advantage of building full-stack applications with their preferred framework alongside Nx’s advanced code generation and project dependency graph, plus a unified experience for both frontend and backend developers.

Visit Nx Cloud to learn more.