Skip to content

Latest commit

 

History

History
112 lines (86 loc) · 4.89 KB

README.md

File metadata and controls

112 lines (86 loc) · 4.89 KB
Raw

QStack

QStack is HackMIT's mentor & help queue platform.

Overview

QStack uses Flask for its backend framework and uses React for its frontend framework.

Directory Overview

qstack/
├── .devcontainer                 # Dev container configuration
├── README.md
├── requirements.txt              # Python dependencies list for backend
├── .env                          # Stores secrets that are not in VCS
├── run.py                        # Flask entry point
├── scripts
│   ├── deploy.sh                 # Deploy to production server
│   └── devcontainer_setup.sh     # Run once when the dev container initializes       
└── client/                       # QStack's React frontend
│   ├── index.html         
│   ├── vite.config.js            # Frontend config for local deployment
│   ├── tsconfig.json             # Config for TypeScript
│   ├── tailwind.config.js        # Config for Tailwind CSS
│   ├── postcss.config.js         # Config for Post CSS
│   ├── package.json              # Node.js dependencies list for frontend
│   ├── public/                   # All the static files that are served by backend in prod
│   └── src/                      # Frontend source
│       ├── api/                  # API routes
│       ├── components/           # Bulk of QStack's UI components
│       ├── hooks/                # Webhook, custom callbacks
│       ├── routes/               # Main pages and routing
│       ├── config.jsx            # QStack's client configuration, modified every cycle
│       ├── index.css             
│       ├── App.jsx               # Code that renders everything
│       └── main.jsx              # Code that renders everything
└── server/                       # QStack's backend folder
    ├── __init__.py               # Has all the setup code for backend
    ├── config.py                 # Holds config for application
    ├── controllers/              # Folder for API endpoints
    │   ├── auth.py               # Router for /api/auth 
    │   ├── queue.py              # Router for /api/queue
    │   └── ticket.py             # Router for /api/ticket
    ├── models/                   # Database ORM schemas for Postgres
    └── data/
        └── tagslist.csv

Requirements

If you are developing using Docker (see setup instructions below), the only requirement you need to install is Docker itself. Otherwise you will need the following versions of the following tools:

Requirement Version
Node.js 18.x.x
Docker 20.x.x
Python 3.9.x

Setup

Env

Copy .env.sample to .env and fill in the necessary values. You should be able to find them on slack.

Docker

Using Dev Containers are strongly recommended when doing development work on qstack. Containers are a way of provisioning identical environments from computer to computer and alleviates a lot of headache when it comes to installing dependencies, setting up Postgres, etc...

To use Dev Containers you must first install Visual Studio Code and Docker. Then you must install the Remote Containers extension for Visual Studio Code.

To use Docker, install it here. To check if your installation is working, try running

docker run hello-world

If you get a message on your screen that starts with "Hello from Docker!", your installation is working.

After that, follow this tutorial to get your environment set up. Make sure you open this repository as a dev container in VSCode.

Note: It can take a few minutes to provision the container if it is your first time starting it up.

Development

To start the server, run

python3 wsgi.py

To start the client, in a different terminal, run

cd client
npm run dev

The client runs on port 6001 and the server runs on port 3001. You should be able to access the website at http://localhost:6001.

License

Released under AGPL v3.0. See LICENSE for more details.