Projects Portal

• Built With
• AWS Services
• Getting Started
• Prerequisites
• Optional Tools
• Installation
• Environment
• Database
• Local Database Initialisation
• Running the Database Locally
• Running Locally
• Prerequisites
• Accessing the Application
• Deployment
• CI/CD
• Author
• License

A full-stack web application for the management of team project assignments, customers and team members. The backend, infrastructure and UI are written in TypeScript. The infrastructure is defined as Infrastructure as Code (IaC) utilising the AWS Cloud Development Kit (CDK) and the UI is a React single page application (SPA).

This repo contains everything required to deploy the application to AWS, the only requirement is an AWS account with the relevant permissions to deploy the associated resources.

Built With

• AWS - Cloud Platform
• NestJS - API framework
• PostgreSQL - Relational Database Management System (RDBMS)
• TypeORM - Database ORM
• React - UI Library
• Vite - React Build Tooling
• Cloudscape - UI Design System

AWS Services

• Amazon CloudFront - Content Delivery Network (CDN)
• AWS WAF - Web Application Firewall
• Amazon Cognito - Authentication
• Amazon API Gateway
• AWS Lambda - Serverless Compute
• Amazon VPC - Virtual Private Cloud
• Amazon RDS - Relational Database Service
• Amazon S3 - Cloud Storage

See this Architecture Diagram for further context.

1. Getting Started

This section will get you started with setting up the codebase locally for development. See Deployment section for notes on how to deploy the project.

1.2. Prerequisites

• Base requirements
  • AWS CLI
  • Node.js v24.x
  • PNPM v10.x0
  • Docker

1.2.1. Optional Tools

• Additional requirements
  • Biome VSCode Extension - For code linting and formatting.

1.3. Installation

Install all dependencies:

pnpm initial-setup

1.4. Environment

• Have a look at ./api/.env.example
• Copy the example to a new file called .env:

cp ./api/.env.example ./api/.env

• The application will need to be deployed to AWS before it can be run locally.
• On successful Deployment the relevant parameters required for the environment variables will be output to the terminal. These need to be configured in the .env file.

1.5. Database

• Technologies used
  • Amazon RDS
  • PostgreSQL
  • TypeORM

This application utilises an Amazon RDS instance deployed inside a private subnet within the VPC. This database is configured on first deployment with an AWS custom resource Lambda function.

To run the application locally it is required to run a local PostgreSQL database.

1.5.1. Local Database Initialisation

To first configure and initialise the local database, with Docker running, execute:

pnpm init:local-db

This will utilise this Docker Compose file to pull and startup a containerised local PostgreSQL database as well as a local PGAdmin server to interface with the database in a browser.

It will also then execute this SQL to initialise the database.

A local containerised postgreSQL database will now be running on port 5432.

1.5.2. Running the database locally

To start an already configured local database instance, execute:

pnpm start:local-db

2. Running Locally

2.1. Prerequisites

• The Database will need to be running locally.
• You will need the AWS CLI with user credentials that have permissions for the application to access the following AWS services:
  • Secrets Manager
  • Amazon Cognito

The local database config will need adding to the environment variables. This config can be found inside the Docker Compose file

The app can now be run locally. To start the backend run:

pnpm start:api

To run the UI locally, run:

pnpm start:ui

2.2. Accessing the application

By default, the UI can be accessed locally by visiting http://localhost:5173/

• The UI will run on port 5173 and the backend on port 3000.
• You will see a landing in screen, from which you can:
  • Sign up
  • Log in
  • You can now:
    • Create, update and delete Customers.
    • Create, update and delete Projects.
      • A Project must to be associated with a Customer
    • Assign / Unassign team members from projects.
• A general user account only has read access - they cannot create / update / delete any entities.
• An admin user has full admin rights in the application.

3. Deployment

To deploy the application you will need an AWS account with permissions for CloudFormation to deploy the application. You may need to first bootstrap the account if it is the first time deploying CDK.

Then run:

pnpm cdk-deploy

4. CI/CD

This repo utilises Husky to execute scripts before every commit and every git push. Before any code is committed and pushed it will be automatically linted, formatted and automated tests will run.

The repo contains a Github Actions Workflow, on every pull request the code will be:

• Checked out
• Dependencies installed
• Dependencies audited
• Linting and formatting checks
• Built
• Automated tests run

Author

• Ashley Taylor - GitHub

License

This project is licensed under the MIT License - see the LICENSE.md file for details