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 application-wide UI
│ ├── src/features/ # Feature-specific code
│ ├── src/pages/ # Application-level pages
│ ├── src/lib/ # Client config and shared utilities
│ └── 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:
mentorA@slu.edumentorB@slu.edugaA@slu.edugaB@slu.edugaC@slu.edugaD@slu.edu
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.