general.md

Documentation / General

Index

• General
  • Index
  • Vocab
  • Tech Stack
  • File Structure
  • Request Flow
• Development
  • Setup
  • Commands
  • Helpful Docs
• Deployment and CI
  • GitHub Actions
  • Site Hosting
  • Data Hosting
• OAuth
  • Overview
  • Future Work
• Email
  • Overview
  • Limitations
• Scripts
  • Overview
  • Scripts
• Front-end Patterns
  • Overview
  • Patterns
• Back-end Patterns
  • Overview
  • Patterns

Vocab

I thought it might help to include some (somewhat oversimplified and project specific) vocab in case any devs are confused by our terminology.

front-end - the visual interface of the app, code that runs on the clients (think: React)

back-end - the web framework and API, code that runs in the cloud (think: ExpressJS)

production - the version of the app that everyone can see (think: not localhost)

deployment - the process of taking code from GitHub and running it in production

CI - "continuous integration", automated builds and tests

model - a common type of object/abstraction (think: user, resource, organization, topic, file)

Tech Stack

We use the fairly common and javascript-only MERN stack.

Front-end

• React
  • Ant Design

Back-end

• ExpressJS
  • JWT
  • mongoose
  • REST

Database

• MongoDB
• AWS s3

File Structure

• /src - the react app
• /src/views - each UI page
• /src/components - reusable react components
• /public - static assets (images, compiled JS libraries, etc)
• /api - the express backend
• /api/routes - RESTful express URL routes
• /api/models - the database models and associated utilities
• /api/lib - misc backend features and utilities
• /.vscode - shared vscode settings for the project

Request Flow

An example flow through the stack. FE = frontend, BE = backend.

1. User visits https://portal.responsible.ai/settings in their browser.
2. FE: Calls /api/context to gather info about the portal and the current logged-in user.
3. BE: Queries user based on token provided in API call and returns result as JSON.
4. User clicks Change Password.
5. FE: Calls API endpoint for changing password.
6. BE: Uses firewall to verify request is valid.
7. BE: Queries user based on token, handles change password logic, return JSON.
8. FE: Shows notification UI.