GradBridge

From graduation to shipped.
An autonomous AI agent workspace for fresh CS graduates — plan, build, debug, optimize, and grow your career.

Quick Start · Features · Architecture · Tech Stack · API · Deployment · Contributing

Screenshots

Landing page with animated terminal demo, feature cards, and dark theme

AI chat with streaming responses, RAG context, and agent mode selector

File orchestrator with diff preview, commit history, and syntax highlighting

What is GradBridge?

GradBridge is a production-ready, multi-user AI agent workspace built for fresh Computer Science & Software Engineering graduates. It combines RAG-powered chat, safe file editing with diff approval, a curated knowledge base, and persistent career memory — all personalized to each user.

Key Capabilities

Feature	Description
6 Agent Modes	Chat, Plan, Build, Debug, Optimize, Career
7 Sub-Agents	Each with tuned system prompts and specialized roles
Enhanced RAG	BM25 + TF-IDF + query expansion + EmbeddingFS
pgvector Search	VECTOR(1536) embeddings for semantic retrieval
Safe File Editing	Unified diff preview with explicit approval before any write
Persistent Memory	University, skills, goals personalize every response
Multi-User Auth	Scrypt-hashed passwords, HMAC-signed session cookies
Real-Time Streaming	Token-by-token SSE rendering
API Key Management	Users bring their own OpenRouter keys for unlimited usage
Free Tier	5 messages/day with shared fallback key
Finetune Pipeline	Feedback tracking + JSONL export for model improvement

Quick Start

Prerequisites

Bun (recommended) or Node.js 18+
Neon Auth account (for production) OR a terminal for local dev
A PostgreSQL database (production) — SQLite works for local dev

Install & Run (Local Dev)

# Clone the repository
git clone https://github.com/rbkhan007/GradBridge.git
cd GradBridge

# Install dependencies
bun install

# Generate Prisma client (SQLite for local dev)
bun run db:generate:sqlite

# Push the SQLite schema & seed data
bun run db:sqlite
bun run db:seed

# Start the dev server
bun run dev               # → http://localhost:3000

The app starts in local auth fallback mode — registration, sign-in, and sessions work without any external dependencies. No Neon Auth credentials needed for development.

First Login

Open http://localhost:3000 — you'll see the landing page
Click Get started to register
Fill your name, email, and password (min 8 chars)
You're automatically logged in and land on the dashboard
Start chatting with the AI agent!

Docker Compose (Self-Hosted)

Full production stack with PostgreSQL 16 + pgvector, Redis, pgAdmin, and auto-migration:

# Clone + enter directory
git clone https://github.com/rbkhan007/GradBridge.git
cd GradBridge

# Copy env template
cp .env.example .env

# Start all services (first build takes ~3 min)
docker compose up -d --build

# App is now running at http://localhost:3000
# pgAdmin at http://localhost:5050 (admin@gradbridge.com / admin)

Services included:

Service	Port	Description
`web`	3000	Next.js standalone server
`postgres`	5432	PostgreSQL 16 + pgvector
`redis`	—	Cache + session backend
`pgadmin`	5050	Database management UI
`prisma-migrate`	—	Auto-runs schema push + seed on first start

Useful commands:

docker compose logs -f web              # watch web logs
docker compose exec web sh              # shell into web container
docker compose exec postgres psql -U gradbridge  # psql shell
docker compose exec redis redis-cli     # redis CLI
docker compose down                     # stop all services
docker compose down -v                  # stop + delete data (fresh start)

Cloudflare Tunnel (free public HTTPS):

# 1. Create tunnel (one-time)
cloudflared tunnel create gradbridge
# 2. Copy the token to .env
# 3. Start with tunnel profile
docker compose --profile tunnel up -d

Production Setup (Vercel + Neon Auth)

For a live deployment, set these environment variables in your Vercel project:

DATABASE_URL="postgresql://user:password@host:5432/gradbridge?schema=public"
NEON_AUTH_BASE_URL="https://your-neon-auth-instance.region.neon.tech"
NEON_AUTH_COOKIE_SECRET="your-32-char-minimum-secret"
NEXT_PUBLIC_APP_URL="https://your-domain.vercel.app"

Auth is handled by Neon Auth — a managed Better Auth service — with automatic fallback to a local cookie-based auth when env vars are unset.

Features

Authentication & Multi-User

Scrypt password hashing — per-user salt, timing-safe comparison
HMAC-SHA256 session cookies — httpOnly, SameSite=Lax, 7-day expiry
Per-user data isolation — every conversation, plan, and profile is scoped
Race-condition safe — Prisma transactions for atomic operations
Anti-enumeration — login always runs password verify

Agent Workspace

Mode	Default Agent	Description
Chat	Coder	Free-form coding help with RAG context
Plan	Plan	Read-only structured plan (approve before build)
Build	Build	Execute approved changes with diff preview
Debug	Debugger	Diagnose errors and propose fixes
Optimize	Optimizer	Performance + readability improvements
Career	Mentor	Roadmaps, resume tips, interview prep

Enhanced RAG Pipeline

Query → Expand (CS/SE synonyms) → Tokenize → BM25 + TF-IDF Hybrid
     → EmbeddingFS search → Score fusion → Dedup → Context windowing
     → Token budget (3000 max) → Inject into LLM prompt

Component	Description
BM25 Scoring	Industry-standard Okapi BM25 for keyword relevance
TF-IDF Vectors	IDF-weighted cosine similarity for semantic-lite matching
Query Expansion	CS/SE-specific synonyms (react→hooks, rag→embedding)
EmbeddingFS	Persistent vector storage on filesystem with cosine search
Context Builder	Token budgeting, deduplication, smart snippet extraction
Finetune	Feedback tracking + JSONL export for model improvement

PostgreSQL + pgvector

VECTOR(1536) — matches OpenAI text-embedding-3-small dimension
HNSW index — fast approximate nearest neighbor search
Row-Level Security — RLS policies on all user-scoped tables
User partitioning — all vector queries scoped with WHERE user_id = $1
ON DELETE CASCADE — strict foreign key cascades for user isolation

Agent Task State Machine

PENDING → RUNNING → SUCCESS
                    → FAILED (retry up to 3x)
                    → TIMEOUT

Prevents duplicate API calls on connection drops
Indexed partial index on pending tasks for fast polling
Retry logic with configurable max retries

SkillAudit Time-Series

Track career growth over time:

Skills scored 0-100 with evidence
AI visualizes growth path by querying audit history
Composite indexes for efficient time-range queries

File Orchestrator

Virtual workspace with syntax-highlighted file viewer
Edit with AI → unified diff preview → approve/reject
Nothing is written without explicit approval
LCS-based diff generator with GitHub-style headers
Git-like commit history with version snapshots

Design System

Emerald/teal developer-tool aesthetic (no indigo/blue)
Full light/dark theme with tuned contrast
Custom animated SVG art library (logo, flow diagram, agent orbs)
Framer Motion transitions, glassmorphism, animated gradient borders
prefers-reduced-motion support
Responsive (mobile-first, Sheet sidebar on mobile)

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Frontend (Next.js 16)                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │  Chat     │ │  Files   │ │  Plan    │ │  Career   │  │
│  │  View     │ │  View    │ │  View    │ │  View     │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘  │
│       └─────────────┼───────────┼──────────────┘        │
│                     └───────────┘                       │
├─────────────────────────────────────────────────────────┤
│                    API Layer (Next.js API Routes)       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │  Auth    │ │  Chat    │ │  Files   │ │  Knowledge│  │
│  │  Routes  │ │  Routes  │ │  Routes  │ │  Routes   │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘  │
│       └─────────────┼───────────┼──────────────┘        │
├─────────────────────────────────────────────────────────┤
│                    Core Lib                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │  Auth    │ │  LLM     │ │  RAG     │ │  Diff     │  │
│  │  (crypto)│ │  (multi) │ │  (BM25+  │ │  (LCS)    │  │
│  │          │ │  provider│ │  TF-IDF) │ │           │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘  │
│       └─────────────┼───────────┼──────────────┘        │
├─────────────────────────────────────────────────────────┤
│                    Database (Prisma ORM)                 │
│  ┌──────────────────────────────────────────────────┐   │
│  │  PostgreSQL + pgvector (production)               │   │
│  │  SQLite (local development)                       │   │
│  │                                                   │   │
│  │  Models: User, UserProfile, Conversation,         │   │
│  │  Message, ProjectFile, KnowledgeEntry, Plan,      │   │
│  │  AgentRun, AgentTask, SkillAudit, VectorEmbedding,│   │
│  │  RagFeedback, UserApiKey, DailyUsage, Commit      │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology	Purpose
Framework	Next.js 16 (App Router)	Full-stack React framework
Language	TypeScript 5	Type-safe development
Styling	Tailwind CSS 4 + shadcn/ui	Utility-first CSS + component library
UI Primitives	Radix UI + Lucide icons	Accessible, composable components
Animation	Framer Motion	Smooth transitions and animations
Database	Prisma ORM	Type-safe database access
Production DB	PostgreSQL 16 + pgvector	Vector embeddings + RAG search
Local Dev DB	SQLite	Lightweight local development
LLM	z-ai-web-dev-sdk + OpenRouter	Multi-provider LLM with fallback
Embeddings	TF-IDF + OpenAI API	Hybrid semantic search
Auth	node:crypto (scrypt + HMAC)	Zero-dependency authentication
State	Zustand (client) + Prisma (server)	Client + server state management
Markdown	react-markdown + react-syntax-highlighter	Rendered agent responses
CLI	Rust (ratatui)	Terminal UI edition

Project Structure

GradBridge/
├── prisma/
│   ├── schema.prisma              # Production PostgreSQL + pgvector schema
│   ├── schema.sqlite.prisma       # Local SQLite development schema
│   └── migrations/
│       └── 001_init/
│           └── migration.sql      # PostgreSQL migration with RLS policies
├── src/
│   ├── app/
│   │   ├── page.tsx               # Single route → GradBridgeApp
│   │   ├── layout.tsx             # Root layout (ThemeProvider, Toaster)
│   │   ├── globals.css            # Design tokens + animations + utilities
│   │   └── api/
│   │       ├── auth/              # register, login, logout, me
│   │       ├── chat/              # POST (non-streaming + SSE streaming)
│   │       ├── plan/              # POST (plan agent)
│   │       ├── agents/            # GET (list agents + modes)
│   │       ├── files/             # GET/POST, diff, apply, commit
│   │       ├── knowledge/         # GET (list/search)
│   │       ├── memory/            # GET/POST (user profile)
│   │       ├── user/
│   │       │   ├── api-key/       # GET/POST (API key management)
│   │       │   └── message-usage/ # GET (daily usage tracking)
│   │       └── chat/clear/        # POST (delete all conversations)
│   ├── components/
│   │   ├── gradbridge/            # 18 custom components
│   │   │   ├── about-view.tsx     # Team page with member cards
│   │   │   ├── agents-view.tsx    # Agent overview dashboard
│   │   │   ├── art.tsx            # Custom animated SVG art library
│   │   │   ├── auth-view.tsx      # Login + register forms
│   │   │   ├── chat-view.tsx      # AI chat with streaming
│   │   │   ├── files-view.tsx     # File orchestrator with diffs
│   │   │   ├── gradbridge-app.tsx # Main app shell + routing
│   │   │   ├── guide-view.tsx     # User guide documentation
│   │   │   ├── knowledge-view.tsx # Knowledge base browser
│   │   │   ├── landing-view.tsx   # Public landing page
│   │   │   ├── memory-view.tsx    # Career memory editor
│   │   │   ├── settings-view.tsx  # API key + usage settings
│   │   │   ├── sidebar.tsx        # Dashboard navigation
│   │   │   └── topbar.tsx         # Top bar with user menu
│   │   └── ui/                    # 40+ shadcn/ui primitives
│   └── lib/
│       ├── auth.ts                # Scrypt + HMAC session auth
│       ├── agents.ts              # 7 agent definitions + prompts
│       ├── llm.ts                 # Multi-provider LLM orchestration
│       ├── rag.ts                 # Enhanced hybrid RAG search
│       ├── context.ts             # System prompt builder
│       ├── diff.ts                # LCS unified diff generator
│       ├── db.ts                  # Prisma client singleton
│       ├── store.ts               # Zustand client state
│       ├── types.ts               # TypeScript type definitions
│       ├── seed.ts                # Database seed script
│       ├── workspace.ts           # Virtual file workspace
│       └── rag/
│           ├── transformers.ts    # BM25, TF-IDF, tokenization
│           ├── embeddings.ts      # TF-IDF + API embedding providers
│           ├── embeddings-fs.ts   # Persistent vector storage
│           ├── context-builder.ts # Token budgeting + dedup
│           └── finetune.ts        # Feedback tracking + export
├── rust-cli/                      # Rust TUI CLI edition
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml
│   │   └── feature_request.yml
│   └── workflows/
│       └── ci.yml                 # GitHub Actions CI
├── CONTRIBUTING.md
├── SECURITY.md
├── DEPLOY.md
├── AGENT.md
├── Dockerfile
├── docker-compose.yml
├── LICENSE                        # Apache 2.0
└── README.md

API Reference

Authentication

Method	Path	Auth	Description
POST	`/api/auth/register`	—	Create user + session
POST	`/api/auth/login`	—	Verify credentials + session
POST	`/api/auth/logout`	—	Clear session
GET	`/api/auth/me`	—	Current user or 401

Agent Chat

Method	Path	Auth	Description
POST	`/api/chat`	✅	Agent chat (non-streaming)
POST	`/api/chat/stream`	✅	SSE streaming chat
POST	`/api/chat/clear`	✅	Delete all conversations
POST	`/api/plan`	✅	Plan agent
GET	`/api/agents`	✅	List agents + modes + providers

File Orchestrator

Method	Path	Auth	Description
GET	`/api/files`	✅	List user files
POST	`/api/files`	✅	Read file content
POST	`/api/files/diff`	✅	Generate unified diff
POST	`/api/files/apply`	✅	Apply approved diff
POST	`/api/files/commit`	✅	Commit version snapshot
GET	`/api/files/commits`	✅	List commit history

Knowledge & Memory

Method	Path	Auth	Description
GET	`/api/knowledge`	✅	List/search knowledge base
GET	`/api/memory`	✅	Get user profile
POST	`/api/memory`	✅	Update user profile

User Settings

Method	Path	Auth	Description
GET	`/api/user/api-key`	✅	Get masked API key
POST	`/api/user/api-key`	✅	Save/delete API key
GET	`/api/user/message-usage`	✅	Get daily usage count

Scripts

# Development
bun run dev              # Start dev server (port 3000)
bun run build            # Production build
bun run start            # Start production server

# Code Quality
bun run lint             # ESLint check
bun run typecheck        # TypeScript type check
bun run test             # Run test suite

# Database (SQLite - Local Dev)
bun run db:sqlite        # Push SQLite schema
bun run db:generate:sqlite  # Generate Prisma client (SQLite)

# Database (PostgreSQL - Production)
bun run db:pg            # Push PostgreSQL schema
bun run db:generate:pg   # Generate Prisma client (PostgreSQL)
bun run db:migrate       # Create + apply migration
bun run db:reset         # Reset database
bun run db:seed          # Seed knowledge base + files

# Docker
bun run docker:up        # Build + start all services
bun run docker:down      # Stop all services
bun run docker:logs      # Watch web logs
bun run docker:reset     # Fresh start (delete data + rebuild)

Environment Variables

# ─── Database ──────────────────────────────────────────────
# Production / Docker: PostgreSQL + pgvector
DATABASE_URL="postgresql://gradbridge:gradbridge@localhost:5432/gradbridge?schema=public"

# Local dev: SQLite (uncomment below, comment out PostgreSQL)
# DATABASE_URL="file:./db/custom.db"

# ─── Neon Auth (required for production) ───────────────────
# Local dev / Docker: leave unset — app falls back to local cookie-based auth
NEON_AUTH_BASE_URL=""
NEON_AUTH_COOKIE_SECRET="generate-a-secret-32-chars-minimum!!"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# ─── LLM Providers (optional — falls back to local responder) ─
ZAI_API_KEY=""
OPENROUTER_API_KEY=""
OPENROUTER_MODEL="deepseek/deepseek-coder"
OPENROUTER_FALLBACK_KEY=""
GROQ_API_KEY=""
GROQ_MODEL="llama-3.3-70b-versatile"
OLLAMA_BASE_URL=""
OLLAMA_MODEL=""

# ─── Docker Compose (override defaults) ──────────────────
POSTGRES_USER=gradbridge
POSTGRES_PASSWORD=gradbridge
POSTGRES_DB=gradbridge
PGADMIN_EMAIL=admin@gradbridge.com
PGADMIN_PASSWORD=admin

# ─── Cloudflare Tunnel (optional — free public HTTPS) ──────
# CLOUDFLARE_TUNNEL_TOKEN=""
# CLOUDFLARE_DOMAIN="gradbridge.yourdomain.com"

Deployment

Vercel (Recommended)

Push to GitHub
Import in Vercel
Set the required environment variables:
- DATABASE_URL — PostgreSQL connection string
- NEON_AUTH_BASE_URL — your Neon Auth instance URL
- NEON_AUTH_COOKIE_SECRET — minimum 32 characters
- NEXT_PUBLIC_APP_URL — your production domain
- ZAI_API_KEY (or other LLM provider key)
Deploy — the build command in vercel.json handles Prisma generation automatically

Docker Compose (self-hosted)

cp .env.example .env              # configure env vars
docker compose up -d --build      # build + start all services

Includes PostgreSQL 16 + pgvector + Redis + pgAdmin + auto-migration. See DEPLOY.md for full instructions.

Railway

Connect your GitHub repo
Set all required environment variables
Deploy

Switching to PostgreSQL

# 1. Update .env
DATABASE_URL="postgresql://user:password@host:5432/gradbridge?schema=public"

# 2. Push PostgreSQL schema
bun run db:pg

# 3. Generate Prisma client
bun run db:generate:pg

# 4. Start dev server
bun run dev

Rust CLI

A terminal UI edition built with Rust (requires Rust 1.75+):

cd rust-cli
cargo build --release
./target/release/gradbridge --help

Commands

Command	Description
`gradbridge login`	Authenticate against the web app
`gradbridge chat "prompt"`	One-shot chat (Chat mode)
`gradbridge plan "goal"`	Plan agent → structured plan
`gradbridge tui`	Launch the interactive TUI
`gradbridge files`	List indexed project files
`gradbridge rag reindex`	Rebuild local RAG index

Local-First Mode

Run without a web backend by passing --local — uses direct Ollama API calls + offline SQLite RAG:

gradbridge --local chat "explain this code"
gradbridge --local plan "build a REST API"

Configure the Ollama endpoint and model:

gradbridge local set-url http://localhost:11434
gradbridge local set-model qwen2.5-coder:7b
gradbridge local check          # verify Ollama is reachable

Features

Local-first mode — Ollama + offline RAG, no auth required
SSE streaming — token-by-token rendering in the TUI
6 agent modes — Chat, Plan, Build, Debug, Optimize, Career
ratatui interface — keyboard-driven, split-pane layout, spinner + context panel

Troubleshooting

Auth Issues on Vercel

Problem: Sign-up or sign-in fails, or getSession returns null on Vercel.

Check:

NEON_AUTH_BASE_URL and NEON_AUTH_COOKIE_SECRET must be set in Vercel project settings (not just .env).
Cookie secret must be at least 32 characters.
NEXT_PUBLIC_APP_URL must match your production domain.
Cold starts — in serverless environments, in-memory auth stores don't persist. The app uses Neon Auth in production to avoid this.

Build Fails — Prisma Client Generation

# Ensure DATABASE_URL is set (format only needed, DB doesn't need to be reachable)
DATABASE_URL="postgresql://user:pass@host:5432/db?schema=public" bunx prisma generate --schema=prisma/schema.prisma

# For local dev with SQLite:
bun run db:generate:sqlite

CI Pipeline

The project includes a GitHub Actions CI pipeline (.github/workflows/ci.yml) that runs:

Type Check & Lint — TypeScript type checking + ESLint
Build — Production build verification
Rust CLI — cargo check on stable Rust (MSRV 1.75)
Integration Tests — Python test suite against the running dev server

Agent Prompts

See AGENT.md for the full system prompts of all 7 sub-agents.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Report bugs via GitHub Issues
Submit pull requests for features and fixes
Join the community and help improve GradBridge

Security

See SECURITY.md for the security policy.

Report vulnerabilities via email
All user data is isolated with Row-Level Security
API keys are masked in responses
Passwords are scrypt-hashed with per-user salts

License

Apache 2.0 — Built for fresh CS graduates, by GradBridge.

See LICENSE for full text.

GradBridge — from graduation to shipped.

_{Designed & Developed by Rhasan}

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.github		.github
prisma		prisma
public		public
rust-cli		rust-cli
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENT.md		AGENT.md
CLOUDFLARE.md		CLOUDFLARE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOY.md		DEPLOY.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
cloudflared-config.yml		cloudflared-config.yml
components.json		components.json
deploy.bat		deploy.bat
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
postcss.config.mjs		postcss.config.mjs
skills-lock.json		skills-lock.json
tailwind.config.ts		tailwind.config.ts
test.py		test.py
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation

GradBridge

Screenshots

What is GradBridge?

Key Capabilities

Quick Start

Prerequisites

Install & Run (Local Dev)

First Login

Docker Compose (Self-Hosted)

Production Setup (Vercel + Neon Auth)

Features

Authentication & Multi-User

Agent Workspace

Enhanced RAG Pipeline

PostgreSQL + pgvector

Agent Task State Machine

SkillAudit Time-Series

File Orchestrator

Design System

Architecture

Tech Stack

Project Structure

API Reference

Authentication

Agent Chat

File Orchestrator

Knowledge & Memory

User Settings

Scripts

Environment Variables

Deployment

Vercel (Recommended)

Docker Compose (self-hosted)

Railway

Switching to PostgreSQL

Rust CLI

Commands

Local-First Mode

Features

Troubleshooting

Auth Issues on Vercel

Build Fails — Prisma Client Generation

CI Pipeline

Agent Prompts

Contributing

Security

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages