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
- Python 3.12+ and uv
- Node.js 20+
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 --reloadAPI available at http://localhost:8000. Interactive docs at http://localhost:8000/docs.
cd ui
# Create ui/.env.local
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
npm install
npm run devUI available at http://localhost:3000.
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_URLset (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.
| 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).
| 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) |
- Create a project in Google Cloud Console
- Go to APIs & Services → Credentials and create OAuth 2.0 credentials (Web application)
- Add your backend callback as an authorized redirect URI:
- Local:
http://localhost:8000/auth/callback - Production:
https://your-api-domain.com/auth/callback
- Local:
- Copy the client ID and secret into your
.env
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 |
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_SECRETGOOGLE_REDIRECT_URI—https://your-api-domain.com/auth/callbackFRONTEND_URL—https://your-frontend-domain.comADMIN_EMAIL(optional) — enablesGET /admin/statsfor 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.
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
# 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# 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 headFrontend checks (mirrors CI):
cd ui
npm run lint
npx tsc --noEmit
npm test # Vitest unit tests
npm run buildPre-commit hooks (ruff lint/format + basic hygiene) run on every commit once installed:
uv run pre-commit installNew 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 dependenciesA 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.