Hoagie Help

Hoagie Help is a peer-help platform for Princeton students. This page explains how the whole system fits together — the parts, how they talk to each other, and where the code for each piece lives.

Features

Q&A

Ask academic questions and get help from classmates.

Sub-feature	Description	Status
Browse & view questions	Question feed, question detail page with answers and comments	🚧 In progress
Ask a question	Post a question with a course, category, and details	🚧 In progress
Answers & comments	Answer a question; comment on answers	🚧 In progress
Hearts	Like questions, answers, and comments	🚧 In progress
Anonymous posting	Post under a stable pseudonym per thread	🗓️ Planned

Study Groups

Form study groups with classmates in your courses.

Sub-feature	Description	Status
Create a study group	Create a group with a meeting time and spot limit	🚧 In progress
Browse & join	Search groups and claim a spot	🗓️ Planned

Notifications

Stay up to date on activity on your posts.

Sub-feature	Description	Status
Activity notifications	Get notified when someone answers or comments on your post	🚧 In progress

User Profiles

See what a user has posted across the app.

Sub-feature	Description	Status
Post history	View a user’s questions, answers, and comments	🗓️ Planned

What We Build With

Tool	What it is, in one line
TypeScript	JavaScript (the language browsers run) plus type checking, which catches many mistakes before the code even runs.
React	A library for building user interfaces out of reusable components — a button, a comment box, a whole page.
Next.js	A framework built on React that handles routing (each folder in `app/` becomes a URL) and running code on the server.
Evergreen UI + Tailwind CSS	Libraries of pre-styled components and CSS shortcuts, so we don’t style everything from scratch.
Zod	Checks at runtime that data from the backend has the shape we expect.
Python / Django	Python is the language; Django is a popular framework for building backends with it.
Django REST Framework (DRF)	A Django add-on for building APIs — endpoints the frontend calls to read and write data, exchanged as JSON (a simple text format like `{ "id": 42, "hearts": 7 }`).
PostgreSQL	A relational database — data lives in tables with rows and columns, like a spreadsheet with rules.
Auth0	A third-party login service. It handles passwords and Princeton logins so we never have to store passwords ourselves.
Yarn / uv	Package managers: they download and track the libraries the frontend (Yarn) and backend (uv) depend on.

System Overview

Here’s how the parts connect. One special detail: the browser never talks to Django directly. Every API call goes through a small proxy — a middleman route inside Next.js — that attaches the user’s login credentials and forwards the request to Django. Why the proxy? When you log in, Auth0 gives the app an access token — a tamper-proof string that proves who you are. If the browser held that token, malicious code on the page could steal it. Instead, the token stays on the server, and the proxy attaches it to each request on the browser’s behalf.

Repo Layout

The repo is one folder with the two programs side by side:

help/
├── frontend/                  # The Next.js app (TypeScript)
│   ├── app/                   # Pages — each folder becomes a URL route
│   │   └── api/hoagie/[...path]/route.ts   # The proxy to Django
│   ├── api/                   # "Service" files — one per resource, all fetch calls live here
│   ├── components/            # Reusable UI pieces (question/, answer/, comment/, ...)
│   ├── lib/hoagie-ui/         # Hoagie's shared design system (Nav, Layout, Theme)
│   ├── proxy.ts               # Sends logged-out users to the login page
│   └── types.ts               # Shared TypeScript types
└── backend/                   # The Django app (Python)
    ├── config/                # settings.py and urls.py (the list of all API routes)
    └── hoagiehelp/
        ├── models/            # One file per database table
        ├── api/               # The code that handles each API request
        └── auth/auth.py       # Checks the Auth0 token on every request

Following One Request Through the System

The best way to understand the architecture is to trace a single action end to end. Here’s what happens when a user hearts (likes) a question: Step by step, with the actual files:

Component (components/question/QuestionPanel.tsx) — the heart button’s click handler calls heartQuestion(id). Components never call the API directly; they always go through a service.
Service (frontend/api/heartService.ts) — builds the HTTP request, sends it to the proxy, and uses Zod to check the response has the right shape. Every resource (questions, answers, comments…) has its own service file, all following this same pattern.
Proxy route (app/api/hoagie/[...path]/route.ts) — grabs the access token from the user’s session and forwards the request to Django.
Auth check (backend/hoagiehelp/auth/auth.py) — Django verifies the token is genuine by checking it against Auth0’s public keys. It reads the user’s Princeton NetID from the token and creates their account automatically on their first-ever request. Every endpoint requires a logged-in user.
View (backend/hoagiehelp/api/heart_views.py) — the function that does the actual work: toggle the heart in the database and send back the new count as JSON.

Two different files have “proxy” in their name — don’t mix them up. frontend/proxy.ts runs when you navigate between pages and redirects you to the login screen if you’re logged out. app/api/hoagie/[...path]/route.ts is the API proxy that forwards data requests to Django.

The Database

In Django, each table is described by a model — a Python class where each attribute becomes a column. Tables point at each other through foreign keys (e.g., every Answer stores the id of the Question it belongs to). Here’s our whole schema and how the tables relate: The core chain to remember: a user asks a question → answers attach to the question → comments attach to answers. Everything else hangs off that chain.

Model	What it stores
`CustomUser`	One row per student: `net_id`, `class_year`, name, email. Created automatically the first time someone logs in and uses the app.
`Question`	A Q&A post: `title`, `details`, `course`, heart count, view count, and whether the asker is anonymous.
`Answer`	An answer to a question: `text`, heart count, anonymity flag.
`Comment`	A comment on an answer (comments don’t attach to questions directly).
`Heart`	One like, by one user, on exactly one question or answer or comment. A database rule prevents liking the same thing twice.
`Notification`	”Someone answered/commented on your post,” plus whether it’s been read.
`StudyGroup`	`title`, `description`, `meeting_datetime`, `max_spots`, one leader, and a list of members.
`Tag`	A question category from a fixed list (`exam prep`, `problem set`, …).
`AnonymousName`	A stable fake name per (user, question), so an anonymous asker keeps the same pseudonym throughout a thread.

Heart counts are stored in two places: as a number on each post (fast to display) and as individual Heart rows (so we know who liked what). The backend updates both together so they never disagree.

API Reference

These are all the requests the backend understands, defined in backend/config/urls.py and grouped by resource below. The method is the kind of action: GET reads data, POST creates (or performs an action), PUT updates, DELETE removes. Every request requires a logged-in user.

Questions

Method	Endpoint	Description
GET	`/questions/`	List all questions (`?title=` search, `?tags=` filter)
POST	`/questions/`	Create a question
GET	`/questions/{id}/`	Read one question
PUT	`/questions/{id}/`	Update a question
DELETE	`/questions/{id}/`	Delete a question

Answers

Method	Endpoint	Description
GET	`/questions/{id}/answers/`	List all answers for a question
POST	`/questions/{id}/answers/`	Create an answer for a question
GET	`/answers/{id}/`	Read one answer
PUT	`/answers/{id}/`	Update an answer
DELETE	`/answers/{id}/`	Delete an answer

Comments

Method	Endpoint	Description
GET	`/answers/{id}/comments/`	List all comments on an answer
POST	`/answers/{id}/comments/`	Create a comment on an answer
GET	`/comments/{id}/`	Read one comment
PUT	`/comments/{id}/`	Update a comment
DELETE	`/comments/{id}/`	Delete a comment

Hearts

Each endpoint toggles a heart on/off and returns {hearts, is_hearted}.

Method	Endpoint	Description
POST	`/questions/{id}/heart`	Heart / unheart a question
POST	`/answers/{id}/heart`	Heart / unheart an answer
POST	`/comments/{id}/heart`	Heart / unheart a comment

Study Groups

Method	Endpoint	Description
GET	`/study-groups/`	List all study groups
POST	`/study-groups/`	Create a study group
GET	`/study-groups/{id}/`	Read one study group
PUT	`/study-groups/{id}/`	Update a study group
DELETE	`/study-groups/{id}/`	Delete a study group

Users

Anonymous posts are hidden when viewing someone else’s profile.

Method	Endpoint	Description
GET	`/users/{id}/`	Get the logged-in user’s profile
POST	`/users/{id}/`	Update the logged-in user’s profile
GET	`/users/{id}/questions/`	A user’s questions
GET	`/users/{id}/answers/`	A user’s answers
GET	`/users/{id}/comments/`	A user’s comments

Notifications

Method	Endpoint	Description
GET	`/notifications/`	All notifications for the logged-in user
GET	`/notifications/{id}/`	Read one notification
POST	`/notifications/{id}/`	Update a notification (e.g., mark as read)
DELETE	`/notifications/{id}/`	Delete a notification

On the frontend, each resource has a matching service file in frontend/api/ (questionService.ts, heartService.ts, …) that wraps these endpoints in easy-to-call functions.

Where to Go Next

Follow the Hoagie Help setup guide to get the app running on your laptop.
Read the development workflow to learn how we use Linear tickets, branches, and PRs.
Open the code and trace the heart-a-question flow from this page yourself: QuestionPanel.tsx → heartService.ts → the proxy route → heart_views.py. Once that path makes sense, you understand the app.

Helpful docs for the tools themselves: React · Next.js · Django · Django REST Framework · Evergreen UI

Home

Quickstart

Architecture

Features

What We Build With

System Overview

Repo Layout

Following One Request Through the System

The Database

API Reference

Where to Go Next

​Features

​What We Build With

​System Overview

​Repo Layout

​Following One Request Through the System

​The Database

​API Reference

​Where to Go Next

Features

What We Build With

System Overview

Repo Layout

Following One Request Through the System

The Database

API Reference

Where to Go Next