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), section code (e.g. 36040), 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.

Note: As of February 2026, AntAlmanac and PeterPortal have unified into a single course-planning platform at antalmanac.com. This repository powers AntAlmanac Scheduler (quarterly schedule planning). Read more in the merge announcement.

Our website is a Next.js application deployed on AWS using SST (Serverless Stack). A summary of the libraries we use are listed below.

• Next.js - React framework with server-side rendering.
• MUI - React UI library.
• React Big Calendar - React calendar component.
• Recharts - React chart component.
• Leaflet - Interactive JS maps.
• Zustand - State management.

• tRPC - type-safe API access layer for the AntAlmanac API.
• Anteater API - API maintained by ICSSC for retrieving UCI data.
• Drizzle ORM - high-performance type-safe SQL-like access layer compatible with all major SQL dialects.
• PostgreSQL - Relational database for storing user data and schedules.

• SST - Infrastructure as code framework for AWS deployment.
• Docker - Containerization for local database development.
• Vitest - Test runner.
• TypeScript - JavaScript with type-checking.

This is a pnpm monorepo:

• apps/antalmanac — the main Next.js web application (AntAlmanac Scheduler).
• apps/aants — AANTS, the class notification service (AWS Lambda + SQS + SES) that watches WebSoc and emails users when a section's enrollment status changes.
• apps/ios — the native iOS wrapper (Swift WebView + push notifications).
• packages/db — Drizzle schema, migrations, and the database client.
• packages/anteater-api — Anteater API types, client, and utilities.
• packages/types — shared internal TypeScript types.

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!

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

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! 🥳

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

1. Install Node.js. This allows you to run JavaScript on your computer (outside of a browser). The required version is pinned in the repo's .nvmrc, so a version manager can read it automatically (nvm use / fnm use). 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-windows

   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.

2. Install pnpm. This is our package manager of choice for this project. The exact version we use is pinned in the root package.json (the packageManager field). It's responsible for installing, uninstalling, and keeping track of the app's dependencies.

   npm install --global pnpm

3. Install Docker. This is required to run the local PostgreSQL database.

   • Docker Desktop - Available for macOS, Windows, and Linux.

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 local PostgreSQL database using Docker Compose.

   docker compose up -d --build

   This will start a PostgreSQL database with the port and credentials defined in docker-compose.yml.

4. Set up environment variables:

   • Copy apps/antalmanac/.env.example to apps/antalmanac/.env and fill in values.
   • Copy packages/db/.env.example to packages/db/.env (same DB_URL as above is fine).
   • For AANTS local runs, use apps/aants/.env.example as a template.

5. Run database migrations to set up the database schema.

   pnpm db:migrate

6. Fetch the static data (course information, term data, etc.).

   cd apps/antalmanac && pnpm get-data

7. Start the development server.

   pnpm dev

8. View the local website at the URL printed in your terminal (by default http://localhost:3000). As you make changes to the application, those changes will be automatically reflected on the local website with hot reloading.

• Database Studio: Open Drizzle Studio to view and manage your local database.

  pnpm db:studio

• Generate Database Migrations: After modifying the database schema, generate a new migration.

  pnpm db:generate

• Run Tests: Execute the test suite.

  pnpm test

• For more detailed contributor documentation, see the AntAlmanac Scheduler docs.

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

AntAlmanac is deployed to AWS using SST (Serverless Stack). The deployment process is automated and managed through the sst.config.ts file.

• Production: Deployed to antalmanac.com (with a www.antalmanac.com alias)
• Staging: Each pull request gets a preview deploy at scheduler-{PR_NUMBER}.antalmanac.com
• Shared staging: staging-shared.antalmanac.com is a persistent environment for cross-team (Scheduler ⇄ Planner) integration testing; deployed manually

Note: Only maintainers with proper AWS credentials can deploy to production.

To deploy the production environment:

pnpm deploy

This command runs sst deploy --stage production which:

1. Builds the Next.js application
2. Deploys the infrastructure to AWS (Lambda, CloudFront, etc.)
3. Updates the live website at antalmanac.com

The variables below configure a full production/staging deployment and are set in your AWS environment or CI/CD pipeline. For local development you only need the variables in apps/antalmanac/.env.example and packages/db/.env.example; anything tagged (optional locally) — maps, analytics, and the Planner integration — can be left unset when running locally.

• DB_URL - Database connection string
• MAPBOX_ACCESS_TOKEN (optional locally) - Mapbox API token for map features
• NEXT_PUBLIC_TILES_ENDPOINT (optional locally) - Endpoint for map tiles
• ANTEATER_API_KEY - API key for Anteater API
• OIDC_CLIENT_ID - OAuth client ID for Google authentication
• OIDC_ISSUER_URL - OAuth issuer URL
• BETTER_AUTH_URL - URL used for OAuth (automatically set based on stage)
• BETTER_AUTH_SECRET - OAuth secret key, you can generate one here
• NEXT_PUBLIC_BASE_URL - Base URL of the site (automatically set based on stage)
• NEXT_PUBLIC_PUBLIC_POSTHOG_KEY (optional locally) - PostHog project key for product analytics
• PLANNER_CLIENT_API_KEY (optional locally) - API key for the AntAlmanac Planner integration

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-windows

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

Try disabling your adblocker or browser extensions that might interfere with local development.

Please reference the .env.example files provided.

If you need production credentials to access the production database or other private resources, please contact a project lead.