expert-octo-system

expert octo system

Links

Prototype (no login required)

Prerequisites

Please ensure the following software / packages are available in your development environment.

The application uses various cloud providers

Optional

Note: The application is developed with a M1 Macbook. As such, there might be slight discrepencies in commands used when building on other systems.

Running the application

Instructions will be divided into 2 sections - backend and frontend. Please use separate terminal windows for each section.

Backend

  1. Ensure terminal is at the expert-octo-backend directory
cd expert-octo-backend`
  1. Install dependencies

It is recommended to install the libraries after creating and activating a virtual environment. To follow along, please ensure that uv is installed.

uv sync
uv pip install docling --extra-index-url https://download.pytorch.org/whl/cpu
uv pip install spacy-layout
uv run -- spacy download en_core_web_trf
uv run -m nltk.downloader punkt_tab
  1. Fill in environment variables

RABBITMQ

Guide from Celery

To run the app locally, there are 2 ways to get a rabbitmq instance.

Docker method

Run the following docker command:

docker run -d -p 5672:5672 rabbitmq

In the .env file: RABBITMQ=”pyamqp://guest@localhost//”

CloudAMQP method

  1. Create an account / sign in to CloudAMQP
  2. Click on Create New Instance button
  3. In the dropdown, select the `Little Lemur (Free) plan
  4. Complete filling in the rest of the details to create a new RabbitMQ instance.
  5. After the instance is created, visit the instance’s page
  6. The URL required is found under the AMQP details section
  7. Copy the URL and filled it in the .env file’s RABBITMQ field

R2

  1. Create an account / sign in to CloudFlare
  2. At the top right hand corner, click on the Add button
  3. Select R2 Storage bucket and fill in the required details
  4. Ensure that 3 different buckets are created (repeat steps 2 to 3)
  5. At the .env file, fill in the last 3 R2 fields with the names of the 3 newly created bucket
  6. At the R2 Storage bucket page, please find the Account Details section and click on the Manage button
  7. The information provided in this page will be sufficient to fill in the first 3 R2 fields of the .env file (Please note that an Account API token needs to be created to obtain the secret access key value)

The application might encounter errors due to the CORS. Please ensure that the urls of the backend and frontend are ‘allowed’ in the CORS Policy of R2 Storage Bucket settings page

SERVICE_ACCOUNT

  1. Create a new Firestore project
  2. Create a Firestore Database, the database should be named: papers (Other names can be used. However, it requires a code change in the shared/firestore.py file)
  3. Create a web app and fill in the require information
  4. After the web app is created successfully, a service account .json file will be provided. Please download this file and saved it in a secured location
  5. Copy the contents of the .json file into SERVICE_ACCOUNT field of the .env file (put ‘’ around the content)
  1. Start up Celery
uv run celery -A tasks worker --pool=solo --loglevel=info
  1. Start up FastAPI server In a separate terminal window, run the following:
cd app
uv run fastapi dev main.py`

Frontend

  1. Ensure terminal is at the expert-octo-frontend directory
cd expert-octo-frontend`
  1. Install dependencies
npm i
  1. Fill in environment variables

BETTER_AUTH_SECRET

Generate a secret key by visiting the better-auth documentation page

In the .env file: BETTER_AUTH_SECRET=[generated secret key]

GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

Follow the guide provided by better-auth to obtain and setup Google Credential authentication

AZURE_SQL values

Follow the guide provided by Azure to spin up an Azure SQL database and fill in the fields required in the .env file

  1. Start up next.js development server 
    npm run dev
  2. Visit the web app in browser

The web app will be served at http://localhost:3000

Paper Prototypes

Overall Reader View Page

Screenshot of the Overall Reader View Page

ToolBar Component in the Reader View Page

Screenshot of the ToolBar Component in the Reader View Page

Screenshot of the ToolBar Component's Mission Area in the Reader View Page

Section Component in the Reader View Page

Screenshot of the Section Component in the Reader View Page

Documents tab in the Home View Page

Screenshot of the Documents tab in the Home View Page

Upload tab in the Home View Page

Screenshot of the Upload tab in the Home View Page

Profile Page

Screenshot of the Profile Page

Architecture Diagram

Screenshot of the Architecture Diagram

User Survey

Screenshot of the User Survey 1/2 Screenshot of the User Survey 2/2