Skip to content
glwjrPublic

About

Track every part of your grad school applications: programs, deadlines, requirements, and recommendation letters.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Dossier

Full-stack PhD application tracker. Keep tabs on programs, requirements, deadlines, recommenders, potential faculty advisors, and draft documents — with weekly email reminders and read-only sharing — all in one place.

  • Backend: FastAPI + SQLAlchemy, deployed on Render
  • Frontend: Next.js 16 App Router, deployed on Vercel
  • Auth: Google OAuth — sign in with your Google account

Local development

Prerequisites

  • Python 3.12+ and uv
  • Node.js 20+

Backend

git clone https://github.com/glwjr/dossier.git
cd dossier

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env — set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and SECRET_KEY at minimum

# Run migrations
uv run alembic upgrade head

# (Optional) seed placeholder programs
uv run python seed.py

# Start the API
uv run uvicorn app.main:app --reload

API available at http://localhost:8000. Interactive docs at http://localhost:8000/docs.

Frontend

cd ui

# Create ui/.env.local
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

npm install
npm run dev

UI available at http://localhost:3000.


Authentication

Google OAuth. Navigate to /auth/login — the server redirects to Google's consent screen; after you grant access, Google redirects to /auth/callback, which sets the JWT as an HttpOnly, Secure, SameSite=Lax dossier_token cookie and redirects to the app. The token is never exposed to JavaScript, so XSS can't exfiltrate it.

  • With FRONTEND_URL set (deployed): redirects to {FRONTEND_URL}/ with the cookie set.
  • Without FRONTEND_URL (local, API-only): also returns {"access_token": …} as JSON for convenience, and still sets the cookie.

get_current_user reads the cookie; UI requests use credentials: "include" (no Bearer token to manage). POST /auth/logout clears the cookie in this browser; POST /me/logout-all invalidates every session. In production set COOKIE_DOMAIN=.your-domain.com so the API-set cookie is readable by the frontend subdomain.


Environment variables

Backend (.env)

Variable Default Description
DATABASE_URL sqlite:///./dossier.db SQLAlchemy connection URL
SECRET_KEY (dev default) JWT signing key — required for local dev; startup rejects the default value when FRONTEND_URL is set
GOOGLE_CLIENT_ID — Google OAuth client ID
GOOGLE_CLIENT_SECRET — Google OAuth client secret
GOOGLE_REDIRECT_URI http://localhost:8000/auth/callback Must match Google Cloud Console
FRONTEND_URL (empty) When set, marks a prod environment: OAuth redirects to {FRONTEND_URL}/, CORS trusts only this origin, the auth cookie is Secure, startup rejects the default SECRET_KEY, and the interactive docs are disabled
COOKIE_DOMAIN (empty) Shared parent domain for the auth cookie in prod (e.g. .dossiertool.com); blank = host-only (correct for localhost)
ADMIN_EMAIL (empty) When set, this user can access GET /admin/stats; blank disables admin access
DEV_USER_EMAIL dev@example.com Email seeded by seed.py
ACCESS_TOKEN_EXPIRE_MINUTES 10080 (7 days) JWT lifetime

Optional feature toggles (all off by default — see .env.example for the full list with defaults): demo login (DEMO_TEMPLATE_EMAIL, DEMO_TTL_HOURS, DEMO_MAX_USERS, DEMO_RATE_LIMIT_PER_MINUTE), error tracking (SENTRY_DSN, SENTRY_TRACES_SAMPLE_RATE), and reminder emails (RESEND_API_KEY, REMINDER_FROM_EMAIL, CRON_SECRET, REMINDER_WINDOW_DAYS).

Frontend (ui/.env.local)

Variable Description
NEXT_PUBLIC_API_URL Base URL of the backend API
NEXT_PUBLIC_MARKETING_URL Marketing site logged-out visitors are redirected to (default https://dossiertool.com)

Google OAuth setup

  1. Create a project in Google Cloud Console
  2. Go to APIs & Services → Credentials and create OAuth 2.0 credentials (Web application)
  3. Add your backend callback as an authorized redirect URI:
    • Local: http://localhost:8000/auth/callback
    • Production: https://your-api-domain.com/auth/callback
  4. Copy the client ID and secret into your .env

API endpoints

Top-level collection endpoints (/programs, /requirements, /deadlines, /recommenders, /advisors, /documents) support opt-in pagination via ?limit= (1–500) and ?offset= query params. With no params, the full collection is returned, so existing clients are unaffected.

Method Path Description
GET /health Liveness check (process is up; no DB access)
GET /health/ready Readiness check (runs SELECT 1; 503 if the DB is unreachable)
GET /admin/stats User signup stats (requires ADMIN_EMAIL; 403 otherwise)
GET /auth/login Redirect to Google OAuth
GET /auth/callback Exchange code for a JWT cookie
POST /auth/demo No-signup demo login (clones the template account)
POST /auth/logout Clear the session cookie in this browser
GET PATCH DELETE /me Current user / update prefs (e.g. email_reminders) / delete account
POST /me/logout-all Invalidate every session (bumps token_version)
POST DELETE /me/calendar-token Generate / revoke the private .ics feed token
POST DELETE /me/share-token Generate / revoke the public read-only share token
GET /me/export Full data export as JSON
GET /calendar/{token}.ics Public token-authenticated calendar feed
GET /share/{token} Public token-authenticated read-only program list
POST /tasks/weekly-digest Send reminder digests (cron-only, X-Cron-Key)
GET /dashboard Per-program summary (completion %, next deadline, blocking requirements)
GET /requirements List all requirements across programs
GET /deadlines List all deadlines across programs
GET /advisors List all potential advisors across programs
GET /documents List all documents across programs
GET POST /programs List / create programs
POST /programs/import Bulk-create programs (max 100 per request)
GET PATCH DELETE /programs/{id} Get / update / delete a program
GET POST /programs/{id}/requirements List / create requirements
PATCH DELETE /requirements/{id} Update / delete a requirement
GET POST /programs/{id}/deadlines List / create deadlines
PATCH DELETE /deadlines/{id} Update / delete a deadline
GET POST /recommenders List / create recommenders (person-level)
PATCH DELETE /recommenders/{id} Update / delete a recommender
GET POST /programs/{id}/recommenders List / assign recommenders to a program
PATCH DELETE /programs/{id}/recommenders/{rec_id} Update / remove assignment
GET POST /programs/{id}/advisors List / create potential faculty advisors
PATCH DELETE /advisors/{id} Update / delete an advisor
GET POST /programs/{id}/documents List / create documents
PATCH DELETE /documents/{id} Update / delete a document

Deployment

Backend — Render

The render.yaml in this repo configures a Docker-based web service (Render Starter plan — always on, no spin-down on idle) and a managed Postgres database (Basic-256mb plan). The health check path is /health. Set the following env vars in the Render dashboard:

  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
  • GOOGLE_REDIRECT_URI — https://your-api-domain.com/auth/callback
  • FRONTEND_URL — https://your-frontend-domain.com
  • ADMIN_EMAIL (optional) — enables GET /admin/stats for this user

DATABASE_URL and SECRET_KEY are handled automatically by Render. Because FRONTEND_URL is set in production, the API restricts CORS to that origin and refuses to start with the default SECRET_KEY.

Database migrations and the demo-template seed run once per deploy via Render's preDeployCommand (sh predeploy.sh). See BACKUPS.md for the backup/restore runbook.

Frontend — Vercel

Deploy the ui/ directory. Set root directory to ui/ in the Vercel project settings, then add:

  • NEXT_PUBLIC_API_URL — https://your-api-domain.com

Docker

# Build
docker build -t dossier .

# Run with SQLite (ephemeral)
docker run -p 8000:8000 dossier

# Run with Postgres and custom settings
docker run -p 8000:8000 \
  -e DATABASE_URL=postgresql://user:pass@host/db \
  -e SECRET_KEY=your-secret \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  dossier

Development

# Run tests
uv run pytest

# Lint + format
uv run ruff check .
uv run ruff format .

# Create a migration after model changes
uv run alembic revision --autogenerate -m "description"
uv run alembic upgrade head

Frontend checks (mirrors CI):

cd ui
npm run lint
npx tsc --noEmit
npm test          # Vitest unit tests
npm run build

Pre-commit hooks (ruff lint/format + basic hygiene) run on every commit once installed:

uv run pre-commit install

After pulling changes

New migrations or dependencies may land on main. After git pull:

uv run alembic upgrade head      # apply any new DB migrations
uv sync                          # sync backend dependencies
cd ui && npm install             # sync frontend dependencies

A sqlite3.OperationalError: no such column … (or the Postgres equivalent) at runtime almost always means a migration hasn't been applied locally — run uv run alembic upgrade head. In production this runs automatically via Render's preDeployCommand.

About

Track every part of your grad school applications: programs, deadlines, requirements, and recommendation letters.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages