kevin-coelho / audioshake-project

Audioshake REST Project

Demo Loom

• https://www.loom.com/share/833936ecd7474b56b6d410d79a912a86

Setup Requiurements

• MacOS Big Sur or later
• Latest version of docker and docker-compose installed on system

Setup Instructions

1. Clone this repo: git clone [e-mail]:kevin-coelho/audioshake-project.git
2. Build the project docker-compose build
3. Create an env file in the project root: .env.docker.development (see sample.env)
4. Start the database docker-compose up -d postgres
5. Migrate the database docker-compose run migrate
6. Start the API docker-compose up api

View API Documentation

1. Ensure the api is running
2. Visit localhost:4001/docs

Run Tests

1. Build the project docker-compose build
2. Create an env file in the project root .env.docker.test (see sample.env)
3. Start the test database docker-compose up -d postgres-test
4. Migrate the test database docker-compose run migrate-test
5. Run tests docker-compose run test
6. Run integration tests docker-compose run integration

Changes from the requirements

• Instead of using plural names, I used singular namings in REST endpoints to reflect database-naming best practices. Database tables also use singular namings.
• The sort paramater was renamed to earliestFirst and latestFirst options to reflect a more client-friendly and user-friendly naming. asc and desc is not always clear when working with date types.
• Some models have additional fields to make them more extensible (such as createdAt and updatedAt fields)

Project Structure

• Dockerfile in the project root. For deployment on infra, simply build the project and run. It is possible to run the entire project on a single machine using docker-compose. For real production environments, separate db and docker image in an image registry is recommended (such as ECR).
• Project is structured as a node.js/typescript mono-repo. apps/server represents a single "app" or "service", in this case a REST API. The project is structured this way to allow more apps to be added such as a React UI / client, or different back-end microservices

Architecture

• Postgres database
• Express / Typescript / Objection.js / knex.js / AWS SDK
• Test framework with: mocha, sinon, chai
• API documentation with swagger (autogenerated from source code and .swagger.yaml files). Inline swagger documentation with jsdoc is also supported /** @openapi ... start docs here */
• File upload is handled using node streams via busboy and aws sdk. Dev build handled 20-50MB files with no problems.
• Assets and posts are assigned unique ids by the back end. For assets, the id is a UUID v5 hash of the asset's bucket, key, and a unique uuidv4. This is to ensure that the system can support assets with identical filenames
• Posts are all assigned unique uuidv4 from the back end. Identical posts are supported.
• API endpoints all have param / query / request validation using joi and celebrate libs.

Code Style

• enforced with eslint and prettier
• Lint and format can be done with docker: docker-compose run lint, docker-compose run format

Packages

• Inside server/src, different modules are organized as importable "packages". This is for code cleanliness, separation of concerns, and also to make good utilization of TypeDI injection / containerization.
• Teams with expertise in different systems (such as s3 or postgres) can each work on modules separately and expose common functionality externally
• Migration to workspaces (such as with npm or pnpm) is easier with this type of organization (simply add a package.json to each package's folder)

Environment Variables

• See packages/config. Environment variables are loaded using dotenv and validated using joi. This ensures that app startup does not have bugs with bad or missing environment variables (config errors will block startup)
• In docker setup, some vars are provided by docker-compose.yaml and others are provided with environment files. In a production setup, all env vars should be provided by the shell environment to the running docker image.