Developers Getting Started

CityAgent Development Guide

Frontend Getting Started and Building

The Frontend uses the Node.js with the npm package manager for its components. Please download at least node v22.22.1 and npm v10.2.5 (earlier or later versions have not been tested) before getting started.

Once Node and npm have been installed, use the following commands to setup the development environment:

Clone the repository (assuming git is already installed)

git clone https://github.com/NotNeelPatel/CityAgent

Navigate to the frontend directory

cd CityAgent/frontend

Important

You will need to set environment variables. See the environment variables page for more information.

Install necessary packages (in the frontend directory)

npm install

If you would like to deploy the frontend, you will need to build CityAgent. This will create a dist/ folder which has the output build contents.

npm run build

If you would like to run the frontend locally, then you will need to run dev. By default, the frontend will run at http://localhost:5173/CityAgent/

npm run dev

For a fully local version of CityAgent, the backend and frontend must be running, and the database and LLM APIs must be configured.

Backend Getting Started

The backend uses Python and various Python AI libraries to run. Python 3.12 is recommended. Other versions of Python are untested. Ensure Python is installed before proceeding. Alternatively, Docker can be used. See Docker Deployment

Once Python is installed, use the following commands to setup the backend environment:

Clone the repository (assuming git is already installed)

git clone https://github.com/NotNeelPatel/CityAgent

Navigate to the backend directory

cd CityAgent/backend

Important

You will need to set environment variables. See the environment variables page for more information.

As with any sort of Python development, it is highly recommended that a virtual environment is set up (though not necessary)

python3 -m venv .venv

Activate the virtual environment

source .venv/bin/activate

Install necessary packages (in the backend directory)

pip install -r requirements.txt

To run the backend locally, use uvicorn. This will start running the backend at http://localhost:8000

python -m uvicorn src.server:app --host 0.0.0.0 --port 8000 --reload

You can test the backend is running by running a curl command

curl -X GET "http://localhost:8000/health"

This should return

{"status":"ok"}

Backend Docker Deployment

It is recommended that CityAgent is deployed using Docker as it simplifies the entire process. Once Docker is installed, use the following commands to setup a Docker environment:

Build the backend image from the backend directory

docker build -t cityagent-backend -f Dockerfile .

To run the docker container locally, use docker run

docker run --rm -p 8000:8000 \
  -v "$(pwd)/backend/src:/app/src" \
  cityagent-backend