The Common App API is used to support Tekalo, a tool for matching tech talent to opportunities at non-profit, philanthropic, and government organizations. A diagram depicting the backend architecture can be found here
- Docker: Docker Desktop is recommended for all operating systems.
- PNPM We use pnpm, a more performant drop-in replacement for npm
1. To install dependencies run:
pnpm container-installFor why we use this instead of the default install command, see important note on node_modules below.
2. Create a root level .env file, and in it put:
# Values for Auth0 client when running tests
AUTH0_CLIENT_SECRET={Auth0 Tenant Client Secret}
AUTH0_CLIENT_ID={Auth0 Tenant Client ID}
AUTH0_DOMAIN={Auth0 Tenant Domain}
# Values will be used to hit the actual Auth0 Service in dev/prod
AUTH0_AUDIENCE="auth0.capp.com"
AUTH0_ISSUER="https://auth.dev.tekalo.io"
AWS_SES_FROM_ADDRESS="tekalo@dev.tekalo.io"
AWS_SES_WHITELIST={Comma separated list of whitelisted emails}
AWS_ACCESS_KEY_ID={AWS Access Key}
AWS_SECRET_ACCESS_KEY={AWS Secret Key}
AWS_SESSION_TOKEN={AWS Session Token}
# NOTE: Only set if you want to actually send events to Sentry
SENTRY_DSN="https://c38ab9f98fd0404f9d2bfb95d015da8d@o4504962952724480.ingest.sentry.io/4504963428777984"
UPLOAD_BUCKET="capp-dev-api-uploads"
# Necessary to execute `pnpm sync-skills`. Create an account on https://lightcast.io/, and use the provided client ID and secret sent to your email.
LIGHTCAST_CLIENT_ID=""
LIGHTCAST_CLIENT_SECRET=""The AUTH0_ prefixed values should come from our dev Auth0 tenant and can be found here.
The AWS_ prefixed values can be found when logging into the AWS Console under your specific user, under Command line or programmatic access
Note: AWS_SES_FROM_ADDRESS is used for sending emails from AWS Simple Email Service. The default value for local development is our dev service account email. Emails in the dev environment will only send to recipients with verified emails
AWS_SES_WHITELIST should be a list of emails that the API should attempt to send emails to when running locally.
We use Docker for local development and testing. This ensures consistency in environments amongst all contributors. Our Docker environment consists of 2 containers: API and Postgres DB containers. The local dev dir is volume-mounted at /api into the container, so there is no need to rebuild the image for code or package changes.
As a general rule, all package.json scripts should be run inside the development Docker container, not on the local host machine. To do so, you can execute:
docker compose run -u node --no-deps --rm api {your-command-here}This will build a docker image of the API and then use it to install NPM packages.
We also make use of a .env file to hold local environment variables.
3. Initialize the Prisma client
pnpm prisma:update4. Build the additional modules in the packages directory
pnpm container-buildRun the following command to launch the API (and a dev postgres instance) in Docker containers in dev mode:
docker-compose upYou can now access the API at http://localhost:3000. The API container uses nodemon and swc to hot-reload and re-build after saving any changes made to .ts files, while typechecking is done with tsc.
The node_modules directory is mounted into the container and all node commands should be run in the container. As far as possible, the pnpm scripts will use docker to run linting, beautification, build, etc in the container. Never run pnpm install outside the container, as it could result in incorrect architecture packages being installed and logged to pnpm-lock. Use pnpm container-install instead, which runs the install in the container.
To add new packages, you can use:
pnpm container-install -- args to pnpm install
# examples
pnpm container-install pino # same as: pnpm install pino
pnpm container-install --save-dev pino-pretty # same as: pnpm install --save-dev pino-prettyIf you do accidentally run pnpm install or otherwise mess up your node modules, deleting your .pnpm-store and node_modules folders should bring you back to a good state.
Below is a diagram depicting the high-level architecture of the API and its related services.
We make use of Prisma as an ORM over our Postgres database
To make experimental database schema changes during local development (that will not use or effect existing migrations) execute:
pnpm prisma:updateTo seed your local instance with test data, execute:
pnpm prisma:seedIf you want to merge changes to schema.prisma into main, you must create a new database migration by executing:
pnpm prisma:migrateTo use the Prisma Studio GUI to view/edit/update your local Postgres database, execute the command below and navigate to localhost:5555. This will spin up an instance of Prisma Studio in a separate docker container.
docker-compose up prisma-studioThe /packages directory is where any additional modules will be stored that are not meant to be part of the larger API module.
All packages within this directory will also be included in the build when pnpm build is executed.
When developing within this directory, it may be useful to use pnpm link to link the local version of this directory to the parent-level API.
We use Jest and Supertest as our testing frameworks. Supertest is used for
our end-to-end testing, while Jest is used for unit testing.
The test script allows you to specify an optional --files flag with pnpm test that argets specific tests. For example:
Run all tests: pnpm run test
Run only tests in the integration folder: pnpm run test --files=integration
Run only tests in the unit folder: pnpm run test --files=unit
Run only tests in the unit/controllers folder: pnpm run test --files=unit/controllers
Run only tests that start with 'grants' in the unit/controllers folder: pnpm run test --files=unit/controllers/applicants
Run only a specific test: pnpm run test --files=unit/controllers/applicants.controller.test.ts
Add AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN to your .env file. The values for these can be found in the AWS start page for the Future Action Networks. Click on Command line or programmatic access under the Future-Actions-Network-Apps account and copy the environment values.
For local development, the docker-compose setup should be setting all of these already:
PORT - (required) host port for API to be exposed on (should be 3000)
DATABASE_URL - (required) URL for Prisma Client to connect to. Formatted as: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:5432/${POSTGRES_DB}
${POSTGRES_HOST}in the local setup will be the name of our docker-compose postgres service
The below are used for the Postgres image in Github Actions CI/CD:
POSTGRES_DB - Name of default database for Postgres container to create
POSTGRES_USER - Username to create in Postgres container
POSTGRES_PORT - Port for Postgres to be exposed (should be 5432)
POSTGRES_PASSWORD - Password to create in Postgres container
POSTGRES_HOST - Hostname of Postgres server
If there are particular rules that you want to add or otherwise toggle, you should generally use the .prettierrc file to configure the rules.
Prettier is an opinionated multi-language code formatter. We use this to make sure our code is consistently formatted.
We also use eslint, specifically airbnb-base to ensure consistent code quality.
The general rule of thumb is: use Prettier for formatting and ESLint for everything else (e.g. code-quality bugs)
This repository uses husky to run git hooks (found in the .husky directory) to aid in development.
Before each commit, husky will run a pre-commit hook to run eslint and prettier formatter on your code to ensure consistent code syntax and style uniformity.
Additional hooks should be added under the .husky directory as seperate scripts and this README should be updated accordingly.
The Tekalo api runs in AWS. The infrastructure configured in terraform files. More information.
More detailed information about the infrastructure can be found here.