Cmugpt Surface

Bark Surface is the user-facing web app and BFF (backend-for-frontend) API for Bark, ScottyLabs’ CMU-focused AI chat assistant. It handles authentication, chat history, memory management, and streams chat responses from the cmugpt-agent service, which does the actual agent/LLM work.

This repo is built on ScottyStack, ScottyLabs’ full-stack typesafe template, so the general ScottyStack docs also apply here. This README covers what’s specific to this project.

Repo structure

This is a Deno workspace with two apps and no separate agent code - the actual chat/LLM logic lives in the sibling cmugpt-agent repo.

cmugpt-surface/
|-- apps/
|   |-- server/            # Express API (BFF) - auth, chat, memory
|   |   |-- src/
|   |   |   |-- server.ts        # entrypoint: migrations, middleware, routes
|   |   |   |-- env.ts           # zod-validated environment schema
|   |   |   |-- controllers/     # tsoa controllers (source of truth for the API)
|   |   |   |-- routes/          # hand-written routes (SSE streaming, auth)
|   |   |   |-- services/        # business logic (chat, memory, preferences)
|   |   |   |-- middlewares/     # error handling, 404s
|   |   |   |-- lib/             # OIDC client, agent HTTP client, auth helpers
|   |   |   `-- db/              # drizzle schema + client
|   |   |-- drizzle/             # SQL migrations (drizzle-kit)
|   |   `-- build/               # generated: OpenAPI spec, routes, types
|   `-- web/                # React SPA
|       |-- src/
|       |   |-- routes/          # TanStack Router file-based routes
|       |   |-- components/      # chat UI, memory manager, icons
|       |   |-- integrations/    # auth + TanStack Query wiring
|       |   `-- lib/api/         # typed API client (generated from server OpenAPI)
|       `-- e2e/                 # Playwright end-to-end tests
|-- nix/, devenv.nix, flake.nix    # Nix/devenv dev environment + build packages
|-- scripts/secrets/               # git submodule: secrets-sync-scripts
`-- secretspec.toml                # declares required env vars / secrets

Key thing to know: apps/server is the source of truth for the API shape. tsoa generates an OpenAPI spec + Express routes from the controllers in apps/server/src/controllers, and apps/web imports the generated openapi.d.ts types directly (see the generate task below) to get a fully typed API client with no manual API type definitions on the frontend.

Tech stack

Before you start

Complete the ScottyLabs setup on docs.scottylabs.org first:

1. A git.cmu.dev account with SSH set up. See Forgejo Setup.
2. Membership in the slai team. Contributing explains how to join a team through governance: add your git.cmu.dev username to members in data/teams/slai.toml and open a PR. This membership is what grants read access to the project’s dev secrets (OIDC client, agent secret, and so on) in OpenBao. Without it you can log in, but secrets fail to load. Credentials and Kennel’s Secrets guide describe how these secrets are stored and loaded.
3. Nix and devenv (below). The shell provides Deno, Postgres with pgvector, the local login relay, bao, and secretspec, so you don’t need to install those yourself. You only need Git.

Installing Nix and devenv

1. Nix, with the Determinate Systems installer on macOS, Linux, or WSL:

   curl -fsSL https://install.determinate.systems/nix | sh -s -- install
   

2. devenv, from a new terminal:

   nix profile install nixpkgs#devenv
   

3. Optionally, direnv with its shell hook, so the environment loads when you cd into the repo.

Logging in to OpenBao (once per machine)

The devenv shell loads secrets from ScottyLabs’ OpenBao as it starts, so it won’t build until you’re logged in. Log in once with the standalone command (it runs before you have bao installed):

nix run git+https://git.cmu.dev/ScottyLabs/kennel#login

A browser window opens for ScottyLabs SSO. The token renews each time you enter the shell, so you only need to log in again on a new machine or after 90 days without using it.

Running it

With devenv (recommended)

git clone ssh://forgejo@git.cmu.dev/ScottyLabs/cmugpt-surface.git
cd cmugpt-surface
devenv shell   # or `direnv allow` if you use direnv
devenv up

Don’t clone with --recurse-submodules. scripts/secrets is a legacy submodule from the old Vault setup that points at a GitHub SSH URL, and you don’t need it.

devenv shell only builds the environment and loads secrets. devenv up starts every process defined in devenv.nix and the shared ScottyLabs module:

• postgres: Postgres with pgvector (devenv exports DATABASE_URL)
• ricochet: the local OAuth relay on 127.0.0.1:8090. Andrew ID login won’t work locally without it.
• api: the server on :3001
• web: Vite on http://localhost:4173

To run the apps yourself (for example, to see their output in your own terminal), start only the supporting services and run Deno in another devenv shell:

devenv up postgres ricochet            # terminal 1
deno install && PORT=3001 deno task dev # terminal 2

PORT=3001 matters: devenv only sets it for its own api process, and without it the server falls back to port 80, which the Vite dev proxy doesn’t target.

By default the server talks to the deployed agent at https://api.cmugpt-agent.scottylabs.org. To use a local agent, run cmugpt-agent with devenv up and set AGENT_API_URL=http://localhost:5055 before starting the server. The agent’s README covers its own setup.

Troubleshooting

• Shell fails with an OpenBao, secretspec, or permission error. Your OpenBao token is missing or expired: re-run the nix run ...#login command above. If login works but secrets still fail, you’re probably not in the slai team yet (see Before you start).
• Check which secrets resolve (reports whether each is present, never the values): secretspec check -P dev
• Server crashes on startup with a zod error. A required variable is missing. Usually DATABASE_URL is unset because Postgres wasn’t started through devenv up.
• See full startup logs: devenv --no-tui shell

Without devenv (not recommended)

Nix is the supported path. Without it, Andrew ID login won’t work locally, because the ricochet relay it depends on is provided by Nix. You can still work on the parts that don’t need login.

1. Install:

   • Git
   • Deno
   • PostgreSQL and the pgvector extension (brew install postgresql@17 pgvector on macOS)
   • OpenBao (brew install openbao on macOS)
   • secretspec (curl -sSL https://install.secretspec.dev | sh)

2. Create a database with pgvector:

   createdb cmugpt_surface
   psql -d cmugpt_surface -c 'CREATE EXTENSION IF NOT EXISTS vector;'
   export DATABASE_URL='postgresql:///cmugpt_surface?host=/tmp'
   export PORT=3001
   

3. Log in to OpenBao (needs slai team membership) and run with the dev secrets injected:

   BAO_ADDR=https://secrets.scottylabs.org bao login -method=oidc
   deno install
   secretspec run -P dev -- deno task dev
   

Migrations run automatically on server startup (apps/server/src/server.ts calls drizzle-orm’s migrate() against apps/server/drizzle before the Express app starts listening).

Environment variables

Declared in secretspec.toml and validated at runtime by apps/server/src/env.ts:

See apps/server/README.md for more on the agent-connection secret.

Common tasks

Run from the repo root (these fan out to the two workspace apps):

Per-app tasks (run with deno task --cwd apps/<app> <task>, or cd into the app first):

• apps/server: server (no regen), tsoa:watch, openapi:watch, start, check
• apps/web: dev, build, preview, test (Vitest unit tests), check

Testing

• Unit tests (apps/web): deno task --cwd apps/web test (Vitest + Testing Library)
• E2E tests: deno task test:e2e from the repo root, powered by playwright.config.ts. It boots the web dev server automatically and runs specs in apps/web/e2e/.
• Type checking: deno task check

Deployment

Deployed via ScottyLabs’ internal kennel platform (see the kennel block in devenv.nix):

• Web (SPA) -> bark.scottylabs.org
• API service -> api.cmugpt.com

flake.nix defines Nix packages (web, api) used to build production artifacts - the API compiles to a standalone Deno binary via deno compile.

Related repos

• cmugpt-agent - the actual chat agent/LLM service this server proxies to (OpenRouter for chat, OpenAI embeddings for memory search, pgvector-backed long-term memory).

License

Dual-licensed under Apache-2.0 or MIT, at your option.