icssc / antalmanac

A course exploration and scheduling tool for UCI Anteaters

About

AntAlmanac is a schedule planner website for classes at UC Irvine. These are some of its features:

• Search bar to easily find classes by department (e.g COMPSCI), course code (e.g. ICS 31), and keywords (e.g. artificial intelligence).
• Integrated calendar to preview class times.
• Quick links to professor reviews, prerequisites, grade distributions, and past enrollment data.
• Interactive map with markers for your class locations.

Technology

Our website is a single page React application hosted on Github Pages. A summary of the libraries we use are listed below.

Frontend

• MUI - React UI library.
• React Big Calendar - React calendar component.
• Recharts - React chart component.
• Leaflet - Interactive JS maps.
• Zustand - State management.

Backend

• tRPC - type-safe API access layer for the AntAlmanac API.
• PeterPortal API - API maintained by ICSSC for retrieving UCI data.

Tooling

• Vite - Blazingly fast, modern bundler.
• Vitest - Test runner.
• AWS - Website deployment and hosting.
• TypeScript - JavaScript with type-checking.

History

AntAlmanac was created in 2018 by a small group of students under the leadership of @the-rango.
They formed an AntAlmanac club to recruit other students and work on new features, so that the website would live on even after its makers graduated.

In 2019, @devsdevsdevs took over as AntAlmanac Project Lead and oversaw a massive rewrite of the codebase, laying the foundation for the AntAlmanac that we know and love today.

In 2020, AntAlmanac was adopted by the ICSSC Projects Committee, which continues to provide funding, marketing, and engineering to support the growing number of users and open-source developers that make up our AntAlmanac Community.

Since then, the project has continued to evolve and grow with successive generations of projects committee members!

Year	Project Lead
2018 - 2019	@the-rango (founder)
2019 - 2021	@devsdevsdevs
2021 - 2022	@ChaseC99
2022 - 2024	@EricPedley
2023 - Present	@ap0nia
2024 - Present	@MinhxNguyen7

Contributing

We welcome open-source contributions 🤗. Here is a rough guide on how to contribute:

Steps

1. Look through the issue tracker or Kanban board to find an open issue (one that hasn't been assigned to anybody) or create your own that describes the problem you want to fix.
2. Fork the repository or create a branch if you have the permission to do so.
3. Setup your development environment
4. Create a draft pull request with your new branch to track your progress.
5. Make any desired changes, commit, and push them. Repeat until the selected issue has been addressed.
6. Change the pull request from draft to open. If possible, request a review from a maintainer.
7. Wait for your pull request to get reviewed and address any requested changes. Repeat until your pull request is approved.
8. Merge your pull request and your changes will appear on the live website shortly! 🥳

Video Walkhrough

We also have a 30 minute contributor video tutorial available on YouTube.

Additional Help

If you ever need help, feel free to ask around on our Discord server.

Development Environment

Pre-requisites

1. Install Node.js. This allows you to run JavaScript on your computer (outside of a browser). This is best done with a version manager that allows you to easily switch between Node.js versions based on the requirements of different projects. Try using any of the following.

   • nvm - Node-Version-Manager.
   • fnm - Fast-Node-Manager.
   • nvm-widows

   If none of those work for any reason, you can defer to your Operating System's package manager or the downloads from the official website. We will be using the latest LTS version, 20.10.0, lts/iron.

2. Install pnpm. This is our package manager of choice for this project. It's responsible for installing, uninstalling, and keeping track of the app's dependencies. npm install --global pnpm

Developing

1. Clone the AntAlmanac repository or your fork. git clone https://github.com/icssc/AntAlmanac.git

2. Navigate to the root directory and install the dependencies. cd AntAlmanac && pnpm install

3. Start the development server for the frontend. pnpm start:aa or cd apps/antalmanac && pnpm dev

4. View the local website at http://localhost:5173. As you make changes to the React application, those changes will be automatically reflected on the local website.

For more information on developing the frontend and backend projects locally, see their respective READMEs.

• frontend
• backend

Typically, you won't need to start the backend server locally because an active development server is available for usage.

However, if you would like to start both the frontend and the backend locally, you can run pnpm start from the project root.

Testing

From the root directory, run pnpm test. Or from any directory, run pnpm -w test.

Troubleshooting

npm i -g <package> fails

This is usually an issue with permissions because npm is trying to install a Node package into a globally accessible location like /bin, which needs admin permissions to do so.

The best way to resolve this is to install Node via any version manager to properly handle these sorts of permissions. Here are the different version managers again.

• nvm - Node-Version-Manager.
• fnm - Fast-Node-Manager.
• nvm-widows

A more convenient, but less secure way to resolve this is to run the command with admin privileges, e.g with sudo.

The React website doesn't seem to load at all

Try disabling your adblocker.

I need the env variables for the backend!

An example .env.sample is provided and can be used by renaming it to .env If you need real credentials to access the database or private resources, please contact a project lead.

antalmanac's Issues

Separate configuration from the code

Currently, the code base is hard coded with some external URLs that can change over time. It would be better to extract all of them into a single configuration file. One reason for that is: we might need different configuration for local testing than the actual production build.

These are some places to look out first: https://github.com/the-rango/AntAlmanac/search?q=amazonaws

Display Course Comments

Some have important information that users might inadvertently miss out on.

Create Privacy Policy

We'll need to mention what information we're storing (course codes, schedule names, etc.) and what information we are tracking (Google Analytics).

Google Analytics might provide specific language for us to include in our privacy policy.

Reduce app bundle size

Right now the bundle (which you can get by running npm run build inside the client directory) stands at ~6.8 MB. This is significantly smaller when g-zipped, but is still way too large and could be trimmed down. We should look into webpack minification customization, make sure tree shaking is working, and also figure out if we want to bundle images and other static files.

Past Enrollment: Improve design

Document main data structures and transformations for class/schedule data

Error handling

Prompt to save before navigating away

For accidentally swiping back in the app, which cleared the schedules the user is drafting.
There should be a confirmation to exiting or hitting the back button.

Laggy When Hover Over Course Code

It's slow to scroll when hover the mouse over the course code on the search result pane. It's normal if I place the mouse somewhere else.

Seaching is slow

It takes two seconds to get the search result back for searching for all CS classes. I noticed that the response time is directly proportional to the number of entries returns back.

sql

currently enrollment history data are kept in a .txt file
very not safe and very inefficient
need to implement sql system asap!

Readme Revamp

• Add project description
• Add screenshot of project
• Add history of project
• Add technologies used

Bad search should not just load indefinitely

#62 related

Document API endpoints

Keep search results page up when switching tabs

Right now, if you search for classes, then go to the maps or added classes tab, going back to the search tab will show you the form. We need to keep the search results pane mounted somehow, with little cost to performance.

mkae it work on ie and edge

pygal graphs not working on either, isee blank
i thinkn just hafta settle for noninteractive graph on those

Remove all inline styles and use the Material UI standard CSS-in-JS solution using withStyles.

There are many instances where we used inline styles for debug/prototyping (and out of carelessness) that we can move to use the standard. This will allow us to easily inject global styles (better dark mode support) and also manage styles at a glance easily.

About Module

• Add "About" button to navbar
• Create a popup module (similar to the notifications one but bigger) for information about the project.

Information to include

• How we're maintained by ICSSC Projects
• Link to Discord (discord.gg/GzF76D7UhY)
• Link to GitHub

Add Zotistics links for grade distribution

Endpoint format: https://zotistics.com/?teacher=PATTIS+R.&selectQuarter=Fall&selectYear=2020-21&selectDep=All+Departments&classNum=&code=&submit=Submit

Implement refresh button

Maps: Customize the popup with compliant design

is the current layout. We should come up with a more compliant and aesthetic design for this.

Design needs to integrate an image carousel since multiple images are available in buildingCatalogue.js now.

Preview color circle appears as transparent instead of the correct color, sometimes

This occurs both on the calendar and in the added classes list:

I'm still able to click the transparent circle to adjust the color of the class.

Add easier way to update ad information

Export as .ICS

Reset button for course search form

Add action to reset forms

Add quick search field that auto populates fields with responses from PeterPortal API

Looking for something better

This is an really amazing project in technical aspects. You guys solve many technical challenges that the AntPlanner was not able to solve. But from a user's persepctive, this app does not offer enough reasons why I should switch from the AntPlanner, which is what I am really familiar with, to the AntAlmanac.

One issue most of AntPlanner's predecessors have is that they look and function exactly the same as the old AntPlanner. There's a weekly calendar on the left half of the page, there's a place where you can search for classes on the right half. You can save or load a schedule using a unique ID. And you can add a class to the schedule by clicking on the class tile.

It's okay to borrow ideas from other apps. But AntPlanner is a crappy app, and that's why you guys are trying to build something that's better. AntPlanner is just an app that a random dude hacked together over a weekend. He didn't design this thing at all. He just grabbed a calendar from a library, put WebSoc into a iframe, then stuff them together in a single webpage. He didn't even bother to add a "Add" button, instead you just click on the class tile to add a class.

I like the material UI that you guys built. It looks really pleasant. And I like the features you guys added here and there. But there no appealing reasons why I would prefer AntAlmanc than AntPlanner. Both of them are the same, it just that one of them has a more modern GUI. I hope you guys can look into some other popular calendar apps outside of UCI, and build something better that the users can just ditch AntPlanner right away.

Mobile site

Instead of adapting the desktop site to be mobile compatible with responsive design, I think we should design a fully mobile experience and deploy on m.antalmanac.com or something like that.

Accounts System - Sign In with Google

Implement "Sign In with Google"

iphone Mobile || Advanced search wonky UI

Bug Reproduction:
-go to mobile
-open drop down for advanced search

Fields overlap each other and the search button
https://media.discordapp.net/attachments/558501572456480780/582630921749004289/image0.png?width=373&height=663

Maps: Refactor and enhancements

• Implement a carousel for multiple images
• If multiple courses are at the same location, show number of overlapping courses and list all courses at the location
• Use addedCourses instead of eventsInCalendar to create markers

Replace all use of `var` with `let` (or `const` when possible)

var leads to hoisting and and should be avoided in modern ES6 code base.

Snackbar not rendering properly

Issue

Potential Causes?

After some digging, I have some guesses

• Something to do with position: relative in .MuiButtonBase-root because disabling it in the inspector "fixes" it but causes problems with the buttons themselves.
• Something to do with the z-index being manually set?
• This article mentions something about absolute vs relative, and which gets the priority during render

Maps: Find a better map solution than using mapbox.

OpenMaps has way better detail on the UCI campus but doesn't allow using its tile servers in production. Currently, we use mapbox but that has less detail on the campus buildings.

PropTypes for every component

Implement SectionTable with material-ui table

• Change vanilla HTML components to Material UI components
• Give each cell max-width so that every table aligns nicely
• Change text and section type colors so that they look good with dark mode
• See if we can optimize mounting of various modals etc (also avoid having every single table listen to the Flux store which warns as a memory leak)

Show Course Overview

The result page for searching all class in CS is super long and it takes a long time to scroll through.
It would be nice to only show an overview of each course on the result page. And we can click on each class the expand to get a detailed description.

Cannot set two events to the same color

Snackbars: Stacking snackbars with notistack

AppStore contains the notification toast/snackbar variables.

https://material-ui.com/components/snackbars/

Calendar - Fix calendar tooltip shifting when adding a class

To reproduce: Add a course, like MATH 2A (44000 from Spring 2020) then open the tooltip for it. Then, search for AFAM 40C (20210 from Spring 2020) and add it. The tootip will suddenly shift to the AFAM events.

"Add Custom Events" box improvements

• Disable "Add Event" button in modal until boxes have been checked to select both the day(s) and the selected schedule(s)
• Add a tool tip message over disabled "Add Event" button indicating that the days and schedule boxes need to be checked.
• Cancel button should clear the event name

News display

I want to add a little box/area where we can put in information about changes, news information, etc. We need to implement a backend endpoint that serves this data to the frontend. We can rapidly and easily change the information displayed by editing the mongoDB with the information we'd like to serve. This would be good for instances where we announce new features or changes or even notices if our services are unavailable (like AANTS) etc.

• Create datatabase location and data model
• Create API endpoint
• Implement frontend

Implement endpoint to automatically add a class to AntAlmanac schedule

MobileCalender.js: Undefined variable 'getDay'

When accessing older schedules on both mobile and desktop (specifically when the window is minimized for desktop), error occurs with getDay variable, declaring it as undefined. Newer schedules work perfectly fine.

Ability to use Paul Revere with New Only Courses

Create functionality to use PR for NOR waitlist closure!

Search query validation

When searching for a class, the user must provide at least one of the following:
GE OR Department OR Course Code/Range OR Instructor.

If all of those are missing, the search button should be disabled.

Missing ./f18.json file?

Seems like the f18.json file doesn't exist in the dir: src/components/AlmanacGraph.

Save/Load registered notification phone number to db along with schedules

This was moved to the backlog because it required more work in that we should prevent registration if someone hasn't loaded in their username.

Light colored events

When changing color of events to light colors, font color should change accordingly for better visibility. Also add border in case of white.

Edit schedule names not working as intended

Unintuitive design
Need to be reflected everywhere