Project Assignments Portal

• Built With
• Getting Started
• Prerequisites
• Optional Tools
• Installation
• Environment
• Database
• Database Init
• Database Seed
• Running Locally
• Running the API & UI Separately
• Accessing the Application
• Deployment
• Author
• License

A full-stack web application for the management of team project assignments, customers and team members. The backend is written in Python and the UI is built using TypeScript. This application is developed to be deployed on Vercel, utilizing vercel serverless python functions for the backend and the NextJS framework for the UI. The application uses a PostgreSQL database and the SQLAlchemy 2.0 ORM, the database also resides on Vercel although it is easily changeable.

Built With

• FastAPI - API framework
• SQLAlchemy 2.0 - Database ORM
• Alembic - Database Migration Tool
• React - UI Library
• NextJS - React Framework
• ShadCN - UI Component Library
• Tailwind CSS - CSS Framework
• Vercel - Cloud Platform

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
  • Alembic 1.13.2+
  • Python 3.12.+
  • Node.js v20.x
  • pnpm v9.9.0

1.2.1. Optional Tools

• Additional requirements
  • Vercel CLI

1.3. Installation

Install all UI dependencies and create a Python virtual environment, from the root directory run:

pnpm initial-setup

Once complete, activate the virtual environment:

source .venv/bin/activate

Now all Python dependencies can be installed:

pnpm api:install-dev

1.4. Environment

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

cp .env.example .env

• Make sure the environment variables are entered:
  • The postgres database url
  • The JWT secret

1.5. Database

• Technologies used
  • Alembic 1.13.2+
  • Vercel Postgres
  • asyncpg

Alembic is the tool used by this project for database migrations.

This project has only been configured and tested using a Vercel postgresql database, if you are attempting to deploy onto an alternative database make sure you adjust the configuration appropriately.

1.5.1. Database Init (Fresh Install Only)

If this is a fresh install and deployment a new database migration will be needed. This will create the tables and data models in your postgresql database.

Make sure that you remove the .versions/ directory first:

rm -rf ./alembic/versions

Then run:

alembic revision --autogenerate -m "initial db config"

This will generate a migration file, to then update your database run:

alembic upgrade head

To create a new migration run:

alembic revision --autogenerate -m "<description of change>"

To deploy the migration to the database:

alembic upgrade head

1.5.2. Database Seed (Fresh Install Only)

Make sure the necessary admin environment variables have been added to the .env file.

From the project root, run:

pnpm seed-database

2. Running Locally

The app can now be run locally. It is possible to run the app in one terminal by simply running the following command from the project root:

pnpm dev

2.1. Running the API and UI separately (optional)

To run the backend and frontend in separate terminals, in the project root, run the following commands in separate terminals:

pnpm api:dev

pnpm ui:dev

2.2. Accessing the application

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

• The UI will run on port 3000 and the backend on port 8000.
• You will see a log in screen.:
  • Login with the defined admin credentials.
  • You can now:
    • Create, update and delete Customers.
    • Create, update and delete Projects.
      • (A Project had to be associated with a Customer)
    • Assign / Unassign team members from projects.
    • Edit your own profile.
• When logged out you can also create new users.
• A general user ('ENGINEER') account only has read access - they cannot create / update / delete any entities. They can update their own user profile.
• An admin user ('MANAGER') has full admin rights in the application.

3. Deployment

To deploy on Vercel you will need an account set up. Vercel can be configured so a deployment runs automatically whenever a change is pushed to the associated GitHub. The vercel.json file contains the necessary config for the deployment to Vercel.

It is also possible to deploy to vercel from the CLI by installing and running the Vercel CLI tool.

By deploying the application on Vercel, the Python backend will be deployed onto a serverless Python function. The UI will be a combination of bundled static pages and a NodeJS serverless function. These services are fully managed by Vercel.

Author

• Ashley Taylor - GitHub

License

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