CougarGrades Monorepo

CougarGrades is a comprehensive tool that helps students explore course evaluations, instructor ratings, historical GPA trends, and academic data for the University of Houston. This monorepo contains the complete full-stack application-frontend, backend API, shared packages, and data services.

📖 Table of Contents

• What is included?
• What isn't included?
• Architecture
• Tech Stack
• Practices
• Contributing
• Resources
• License

What is included?

The monorepo includes:

• Web App (@cougargrades/web) - A static React application deployed to Cloudflare Pages
• API (@cougargrades/api) - An HTTP API (Cloudflare Workers with Hono) that powers the web app and serves third-party data
• Shared Packages - Core models, services, utilities, and vendor integrations used across the stack

What isn't included?

⚠️ None of the following are included in this monorepo:

• The web scraping scripts and source data acquired from the University of Houston.
  • That can be found in the @cougargrades/publicdata repository linked below.
  • https://github.com/cougargrades/publicdata/tree/master/documents
• The scripts used to combine and transform the source data into a CougarGrades-specific NoSQL database
  • That can be found in the @cougargrades/publicdata repository linked below.
  • https://github.com/cougargrades/publicdata/tree/master/bundler
  • https://github.com/cougargrades/publicdata/tree/master/mock-database
• Direct access to the production Firestore database that is populated based on data in the @cougargrades/publicdata project.
• The Firestore REST API client that is compatible with the Cloudflare Workers runtime.
  • That can be found in the @cougargrades/firebase-rest-firestore repository linked below.
  • https://github.com/cougargrades/firebase-rest-firestore
  • It is a fork of the package developed by @nabettu

Architecture

cougargrades-monorepo/
├── src/
│   ├── apps/                     # Deployable applications
│   │   ├── api/                  # Cloudflare Workers backend (Hono + D1)
│   │   └── web/                  # React frontend (Vite + TanStack)
│   │
│   └── packages/                 # Shared libraries
│       ├── models/               # Zod schemas & data models
│       ├── services/             # Type-safe API clients
│       ├── vendor/               # External service wrappers (RMP, GitHub, etc.)
│       ├── utils/                # Common utilities & helpers
│       └── atom-feed/            # Atom feed parser (used for checking blog and posting messages on the site)

Data Flow:

1. Frontend (React) fetches data from the API using @cougargrades/services
2. API (Hono) retrieves data from Firestore, Cloudflare D1, or vendor services
3. All responses validated with Zod schemas from @cougargrades/models
4. Shared logic in @cougargrades/utils and @cougargrades/vendor

Tech Stack

Deployable applications

• Frontend (@cougargrades/web)
• Backend (@cougargrades/api)

Shared Libraries

• Models (@cougargrades/models) - Zod schemas for type safety and validation
• Services (@cougargrades/services) - Type-safe API client libraries
• Vendor (@cougargrades/vendor) - External service integrations
• Utils (@cougargrades/utils) - Shared utility functions
• Atom Feed (@cougargrades/atom-feed) - Atom feed parser

Core

• Language: TypeScript with strict mode
• Package Manager: pnpm (monorepo workspaces)
• Deployment: Cloudflare (Workers + Pages)

Practices

TypeScript & Type Safety

• Strict Mode Enabled: All TSConfig files use "strict": true
• Zod Validation: Runtime validation with Zod schemas ensures data integrity at API boundaries
• No Implicit Any: Type inference is preferred over any types
• ES Module System: Modern "type": "module" throughout

Code Organization

• Monorepo with pnpm Workspaces: Separate apps/ for deployable projects and packages/ for shared libraries
• Clear Dependency Boundaries: Apps depend on packages; packages can depend on other packages but not apps
• Consistent Naming: @cougargrades/ scoped package names

Testing

• Vitest: Lightning-fast unit testing (used in atom-feed package)
• Test Patterns: Focused on critical paths and data validation

Contributing

We welcome contributions from the community! Whether you're interested in fixing bugs, adding features, or improving documentation, check out CONTRIBUTING.md for detailed instructions.

Resources

• Live Site: https://cougargrades.io/
• API Documentation: https://api.cougargrades.io/
• License: MIT (see LICENSE)