Welcome to the GradEval360 development team! This project is the centralized performance management platform for Saint Louis University's Graduate Assistants.
Our current milestone work completes the full Milestone 2 annual evaluation workflow. That includes expectation setting, GA acknowledgment, GA self-evaluation, mentor evaluation, admin sign-off, status reporting, and dashboard visibility through FinalEvaluated.
We have a dedicated guide to help you set up your machine. Please follow this first to ensure your environment is ready:
- Environment/setup guide: docs/setup.md
- Okta app setup + troubleshooting + smoke test: docs/OKTA_SETUP_AND_SMOKE_TEST.md
Make sure these are installed before you start:
- Node.js v20+ and npm v10+ (
node -v,npm -v) - Docker Desktop (
docker --version) - Git (
git --version)
If anything is missing, follow the instructions in docs/setup.md.
This is a monorepo, meaning all the code for the website, the server, and the database lives in this one folder. Here is a map of the project to help you find your way:
GradEval360/
├── client/ # Frontend (React + Vite)
│ ├── src/components/ # Reusable UI pieces (Buttons, Inputs, Sidebar)
│ ├── src/pages/ # Full views (Login, Dashboard, Appointments)
│ ├── src/lib/ # Client config (Auth client, API fetchers)
│ └── src/hooks/ # Shared React hooks
├── server/ # Backend (Express.js)
│ ├── drizzle/ # Drizzle migrations output
│ ├── src/db/ # Database schema, migrations, and seed data
│ ├── src/routes/ # API endpoints (The URLs the frontend calls)
│ ├── src/middleware/ # Security checks (Checking if you are logged in)
│ └── src/scripts/ # One-off scripts (seeding, backfills, etc.)
├── shared/ # Shared Logic (The "Glue")
│ ├── schemas/ # Shared Zod schemas
│ └── src/ # Shared types/build outputs
├── docs/ # Team docs (setup, auth, references)
└── docker-compose.yml # The "Command Center" to start your database
client/src/owns UI rendering, page state, and browser interactions.server/src/routes/*.tsowns HTTP orchestration, whileserver/src/routes/*.logic.tsowns pure workflow logic.shared/schemas/owns contracts shared by client and server.client/tests/,server/tests/,shared/tests/, andtests/own test code and fixtures only.
See tests/TESTING.md for the repository testing strategy.
For a high-level system view, see:
- Diagram source: docs/architecture.mmd
- Rendered SVG: docs/architecture.svg
If you’ve already met the prerequisites, this is the shortest path to running the app locally:
# 1. Install workspace dependencies
npm ci
# 2. Build shared schemas/types
cd shared && npm run build
cd ..
# 3. Start database containers
docker-compose up -d
# 4. Initialize database (schema + seed)
cd server && npm run db:setup
cd ..
# 5. Run backend and frontend in separate terminals
cd server && npm run dev
cd client && npm run devCreate server/.env and set the required values. You can copy the example below and fill in real values:
# Database
DATABASE_URL=postgres://user:password@localhost:5432/gradeval360
# Okta OIDC
OKTA_ISSUER_URL=https://your-okta-domain.okta.com/oauth2/default
OKTA_CLIENT_ID=your_okta_client_id
OKTA_CLIENT_SECRET=your_okta_client_secret
OKTA_POST_LOGIN_REDIRECT_URL=http://localhost:5173
# Better Auth
BETTER_AUTH_SECRET=your_long_random_string
BETTER_AUTH_URL=http://localhost:3000For more detail, see docs/OKTA_SETUP_AND_SMOKE_TEST.md.
Run these from the repository root unless noted otherwise:
- Install dependencies:
npm ci - Build shared package:
cd shared && npm run build - Start backend:
cd server && npm run dev - Start frontend:
cd client && npm run dev - Initialize DB (schema + seed):
cd server && npm run db:setup - Push DB schema changes:
cd server && npm run db:push - Auth smoke test:
cd server && npm run smoke:auth - Run all automated tests:
npm test
The local seed data includes the shared mentor and GA identities below for smoke testing and workflow verification:
[email protected][email protected][email protected][email protected][email protected][email protected]
If you need credentials for those accounts, retrieve them from the team’s approved secret store instead of committing them to the repository.
Use these to verify everything is running correctly:
- Backend health:
http://localhost:3000/api/health - User API (not signed in):
http://localhost:3000/api/me(expected 401) - Database UI (pgAdmin):
http://localhost:8080 - Okta login start:
http://localhost:3000/api/auth/signin/okta
Helpful references in docs/:
- Setup guide: docs/setup.md
- Okta setup + smoke test: docs/OKTA_SETUP_AND_SMOKE_TEST.md
- Auth tables and flow: docs/AUTH_TABLES_AND_FLOW.md
- Appointment status enum: docs/status-enum.md
- Product strategy draft: docs/strategy/product-strategy.md
- Community strategy draft: docs/strategy/community-strategy.md
- Threat model: docs/security/threat-model.md
The annual evaluation lifecycle now progresses through these statuses:
AwaitingExpectationSetting -> ExpectationSet -> AwaitingSelfEvaluation -> SelfEvaluationCompleted -> MentorEvaluationCompleted -> AwaitingSignOff -> FinalEvaluated
We welcome contributors. Start with CONTRIBUTING.md for setup, issue labels, and PR expectations.
- If
npm cichangespackage-lock.json, don’t commit unless you added/updated a dependency. - If the DB UI can’t connect, try
docker-compose down -vand re-run setup. - If auth fails, follow the policy/redirect checks in
docs/OKTA_SETUP_AND_SMOKE_TEST.md.
This project uses a TypeScript-based stack across the frontend, backend, and database layers.
- Frontend: React + shadcn/ui
- Backend: Node.js + Drizzle ORM
- Database: PostgreSQL
- Authentication: Better Auth with a mock Okta / OIDC development flow
This project is licensed under the BSD 3-Clause License. See LICENSE for details.