TUM.ai Space 🚀

TUM.ai Space is an all-in-one platform with the purpose of tracking all internal processes related to members. This entails: development, performance, projects, and recruitment.

TUM.ai Space solves the following issues:

• Lack of a clear, systematic, observable overview of members' achievements
• Decoupled nature of the existing systems and the lack of extensibility thereof

Hence, TUM.ai Space facilitates the following:

• Increased observability of TUM.ai's existing stakeholder data and projects in addition to prospective stakeholder data
• Centralized organization of internal information that is setup in an extensible and manageable format

Organization

Project planning is conducted through Linear. All relevant issues and tasks are managed there - Github Issues should not be considered for development.

For instructions on working and developing a Linear ticket, please refer to this section.

Repo Structure

Directory	Explanation
.fileserver/certification/	Resources needed for generating a certificate
.github/workflows/
api/	Backend, services
app/	Frontend

Development

Installation and Prerequisites

Consider the following as an ordered checklist of prerequisites for running TUM.ai Space

• Linux Only: build/dev tools, mainly for make

1. Homebrew: See here
2. Node + NPM: See here
   
3. Docker + Docker Compose: See here
4. Micromamba or Anaconda: See (recommended) Micromamba or Anaconda
5. Create the development environment using environment.yml:
   

If you have Anaconda:

~ cd api
~ conda env create -f environment.yml

If you have Micromamba:

~ cd api
~ micromamba env create -f environment.yml

6. (Optional but recommended) Pyenv: See documentation and installer
7. Signing your commits with GPG: See here - this is highly encouraged but not necessary

Setup

Initial setup
For MacOS:

1. Find your python version
2. Execute the following:

open /Applications/Python\ {your python version}/Install\ Certificate.command

For Linux, MacOS, Windows:

1. Create .env within /api
2. Paste this into /api/.env
3. Create .env within /app and paste in the following:
4. Create /api/.secrets and then /api/.secrets/tumai-space-firebase-adminsdk.json
5. Paste this into /api/.secrets/tumai-space-firebase-adminsdk.json - Add Firebase Admin SDK Certificate (for staging env): the development environment will use authentication of the Staging Firebase project

Running the Project

Backend in /api/

1. Change into the api directory:

~ cd api

2. Activate the Conda environment using either Micromamba or Anaconda:

~ micromamba activate space

or

~ conda activate space

3. Run the backend:

(Recommended)

~ uvicorn space_api.main:app --host 0.0.0.0 --reload --port 8000

or

~ make run  # in root dir (launch api in docker container)

Frontend in /app/

1. Install the project's frontend dependencies listed in the package.json file, create a node_modules directory and ensuring the correct package versions are used:

~ cd app
~ npm install

2. Start a development server for the frontend using npm:

~ npm run dev

Using the precommit hook

To trigger this manually:

~ pre-commit run --all

To trigger this on every commit:

~ pre-commit install

Deploying to Firebase (hosting) manually / using Firebase local emulators:

Consider checking out the commands listed in /app/Makefile.

Please only use them if you know what you are doing!

Generating mock data

Generate mock users, opportunities, applications and reviews using faker scripts.

How to generate mock data:

1. Run local DB

   docker-compose up

2. Login via Slack Authentication

   • Open the UI and log in via Slack authentication. This will create a session and a User entry in the DB.

3. Seed local DB

   • Run the following command to seed the local DB with mock data:

   bun db:seed

Command Line Options:

~ bun db:seed -h

Reset/Clear DB:

~ bun prisma migrate reset

Working on a Linear ticket

Working with Linear tickets is very similar to working with GitHub issues. It works as follows:

1. Start by clicking on the chosen ticket
2. Click on the branch icon in the top left corner to copy the branch name - this allows Linear to track the ticket status and progress
3. Now locate the space repository and create a new branch:

~ git switch -c <branch-name>

4. Now push the branch and changes at first with:

~ git push --set-upstream origin <branch-name>

Technology Stack

In the beginning of the project the team formed and chose a technical stack. This will not be changed and is a final decision.

Backend:

• Service Logic: Python using FastAPI framework (apiDocs via Pydantic models)
• Database: PostgreSQL on Azure through SQLAlchemy 2.0

Frontend:

• NextJS framework for the website
• MobX for state management
• Firebase Auth for authentication

Deployment:

• Backend and Database (DB) on Azure - this will be moved to Google Cloud in the future
• Firebase Authentication for managing authentication, authorization and roles
• Docker with Docker Compose for containerization and orchestration of the backend and DB

Documentation

To view an Entity-Relationship Diagram (ERD) of the system, paste api/docs/erDiagram file into a mermaid-style viewer like this. Alternatively, checkout the /api/README.md on GitHub.

Documentation on the frontend and backend as well as instructions on how to add services, pages, etc. can be seen on the linked Notion pages.

FAQ

A section with common errors and how to solve them can be found on this Notion page, documenting the project.

DevOps:

• Deployed on Azure
• Firebase for managing authentication
• Docker with Docker Compose for containerization and orchestration

2. Staging

• Deployed version of the staging branch
  • Frontend deployed to Firebase staging project ("tumai-space-staging")
  • Backend deployed to Azure Staging
  • Uses an Azure Staging DB
• Continuous-Integration (CI) Action is triggered on Pull-Request (PR) creation into main

3. Production:

• Deployed version of the main branch
  • Frontend deployed to Firebase production project ("tumai-space")
  • Backend deployed to Azure Production
  • Uses an Azure Production DB
• CI Action triggered on push commit to main (=merge PR)

One could also see the Testing CI part as an environment:

• Runs linting & unit tests on every pushed commit of all branches
• No deployment
• Uses an Azure Dev DB