Skip to main content
Prerequisite: Complete Getting started (Node 20, MongoDB, gh, clone, npm run setup, and .env) before using this page.

​
Conventions (read these first)

Product rules and code patterns live in two dedicated guides—this page stays workflow-oriented (commands, layout, debugging). When you touch code, start from the right doc:

Web client best practices

Meridian/frontend/ — useFetch, postRequest (no direct axios), dev proxy to port 5001, routing, SCSS/Tailwind, and ESLint entrypoints.

Backend best practices

Meridian/backend/ — getModels(req, …), req.db / req.globalDb, verifyToken, org permissions, and how events routes mount.

​
Monorepo layout

You clone the Meridian repo first (Meridian/ is a real git checkout). Events-Backend/, Meridian-Mobile/, and this docs site are separate checkouts or folders you place next to Meridian on disk when needed. Some teams call that sibling layout “Meridian-Mono”—it is a folder convention, not something you git clone as one repository. 
workspace/                    # any parent directory (not a git repo)
├── Meridian/                 # clone of Meridian — daily driver for web + API
│   ├── frontend/
│   ├── backend/              # Express entry: server.js
│   │   └── events/           # Symlink → ../Events-Backend when using meridian CLI
│   ├── bin/meridian.js
│   └── package.json          # dev, server, client, test:*
├── Events-Backend/           # private module; sibling of Meridian/ when linked
├── Meridian-Mobile/          # optional: separate Expo / React Native clone
└── Meridian-Mintlify/        # optional: this documentation site
Unless a doc says otherwise, run install, dev, and test commands from Meridian/ so concurrently and path assumptions match CI and the rest of the team.

​
Run the app locally

From Meridian/:
ScriptWhat it does
npm run devRuns npm run server and npm run client together (see Meridian/package.json). Default URLs: frontend http://localhost:3000, API http://localhost:5001.
npm run servernodemon + node --preserve-symlinks backend/server.js — Express API with reload.
npm run clientcd frontend && npm start — webpack dev server for the React app.
Run API and web separately (two terminals, still from Meridian/): 
npm run server

npm run client
Do not rely on cd Meridian/backend && npm start — the backend package.json does not define a start script; the supported entry is npm run server from Meridian/.

​
Custom ports

  • API: backend/server.js uses process.env.PORT and defaults to 5001. 
    PORT=5002 npm run server
  • Frontend: the CRA-style dev server respects PORT when you start the client (from Meridian/): 
    PORT=3001 npm run client
Keep the frontend package.json proxy target aligned with wherever the API listens (default http://localhost:5001/).

​
Branching and CLI

Use the Meridian CLI for branch names that match automation (for example MER-123-short-slug), syncing Events-Backend, and shipping. Install gh and run gh auth login (see Getting started — GitHub CLI) so meridian ship can open and merge PRs. Plain Git is fine for small fixes; for anything touching the private events module or lockfile, follow the CLI doc.

​
Testing

From Meridian/: 
npm run test:ci          # backend coverage + frontend coverage (matches a large part of CI)
npm run test:backend     # Jest in backend/
npm run test:frontend    # Jest in frontend/
See Testing for test:unit / test:integration / test:routes, folder layout, and how GitHub Actions maps jobs.

​
Linting

There is no root npm run format or npm run type-check in Meridian/package.json. Formatting is team/IDE-driven unless you add scripts yourself. Frontend (ESLint config lives in Meridian/frontend/package.json): 
cd Meridian/frontend && NODE_ENV=development npx eslint src/
Backend: there is currently no lint script in Meridian/backend/package.json; rely on your editor and the patterns in Backend best practices until a shared script exists.

​
Debugging

​
Frontend

  • React DevTools in the browser.
  • Network tab: confirm requests go to relative URLs so the dev proxy and cookies behave (see Web client best practices).
  • Remove stray console.log before merge.

​
Backend

  • Logs in the terminal running npm run server.
  • debugger breakpoints under Node inspect if you use that workflow.
  • curl / Postman / Insomnia against http://localhost:5001 (or your PORT).

​
MongoDB

Use mongosh with the same URI as Meridian/backend/.env (for example MONGO_URI_RPI or MONGODB_URI). See Getting started — Environment variables and Update local database for data refresh. 
mongosh "mongodb://127.0.0.1:27017/<your-db-name>"
show collections
db.users.find().limit(5)

​
Environment variables

Do not commit real .env files. The repo may not ship a single .env.example at the repo root—follow Getting started — Environment variables for which files to create (Meridian/backend/.env at minimum) and typical keys (JWT_SECRET, Mongo URIs, NODE_ENV).

​
Common issues

Reinstall from the package that owns the dependency:
cd Meridian/frontend && rm -rf node_modules && npm install
cd Meridian/backend && rm -rf node_modules && npm install
From Meridian/ you can also reinstall root tooling deps: rm -rf node_modules && npm install.
macOS / Linux
lsof -ti:3000 | xargs kill
lsof -ti:5001 | xargs kill
Windows (PowerShell)
netstat -ano | findstr :3000
netstat -ano | findstr :5001
taskkill /PID <pid> /F
Confirm MongoDB is running and the URI in Meridian/backend/.env matches your local database name. macOS (Homebrew): brew services list. Windows: Services (services.msc) or net start MongoDB. See Getting started — Prerequisites.
Ensure the API process is up, the browser is on the same origin/proxy path you expect, and that CORS / cookie settings match how you are hitting the API (see Web client best practices).

​
Before you open a PR

  • Run npm run test:ci (or at least the suites you touched).
  • Follow MER-* / CLI conventions when your work spans Events-Backend or the lockfile—see Meridian CLI and Deployment.
  • Prefer conventional commits (feat:, fix:, docs:) so history stays readable.

Getting started

Stack, MongoDB, gh, npm run setup, and first-run env vars.

Testing

Backend vs frontend tests, route-outcomes, and CI alignment.

Web client best practices

useFetch, postRequest, proxy, and UI conventions.

Backend best practices

Multi-tenant req.db, auth, and route patterns.

Authentication overview

How login, JWTs, and cookies line up with the dev proxy.

Multi-tenant identity

Subdomains, global DB, and how req.user resolves locally.

API reference

HTTP surfaces the web app calls through useFetch / postRequest.

Meridian CLI

Branches, Events-Backend, lockfile, and meridian ship.
For credentials, tenant Atlas URIs, or production access, use internal Study Compass engineering channels—not this docs site.