Backend AI Agent Guide

​

Architecture overview

• Stack: Express, Mongoose, JWT (cookies + Bearer), optional Passport/SAML.
• Multi-tenant DB: Tenant is derived from subdomain (e.g. rpi from rpi.meridian.study). In development, localhost and IP hosts default to rpi.
• Per-request DB: Every request gets req.db (a Mongoose connection) and req.school (subdomain string) from a global middleware in app.js.

​

Database and models

​

Getting models (required pattern)

const getModels = require('../services/getModelService');

// In a route or service that has req:
const { User, Event, Org } = getModels(req, 'User', 'Event', 'Org');

• Why: req.db is the tenant-specific Mongoose connection. getModels(req, ...) registers schemas on req.db and returns the correct model instances for that tenant.
• Where: Use in routes and in services that receive req (e.g. userServices.js, studySessionService.js). If you add a new service that touches the DB, have the route pass req and use getModels(req, ...) inside the service.
• Do not: Use require('../schemas/user') and then mongoose.model('User') or any global mongoose connection for app data. That bypasses multi-tenancy.

​

Adding a new model

​

Connections manager

• File: Meridian/backend/connectionsManager.js
• Role: Maintains a pool of Mongoose connections per school and exposes connectToDatabase(school).
• Usage: Only app.js calls it. The middleware in app.js sets req.db = await connectToDatabase(subdomain) and req.school = subdomain.
• Adding a school: Extend the schoolDbMap in getDbUriForSchool() with the new subdomain and env var (e.g. MONGO_URI_<SCHOOL>). Fallback is DEFAULT_MONGO_URI.

​

Auth and middlewares

​

Order of use

• verifyToken or verifyTokenOptional must run before any middleware or handler that uses req.user.
• Org middlewares (requireOrgPermission, etc.) expect req.user and use getModels(req, ...); they must run after verifyToken.

​

verifyToken.js

const { verifyToken, authorizeRoles } = require('../middlewares/verifyToken');

router.get('/admin-only', verifyToken, authorizeRoles('admin'), async (req, res) => {
  const { User } = getModels(req, 'User');
  // ...
});

​

orgPermissions.js

const { requireOrgPermission } = require('../middlewares/orgPermissions');
const { ORG_PERMISSIONS } = require('../constants/permissions');

router.post('/orgs/:orgId/events', verifyToken, requireOrgPermission(ORG_PERMISSIONS.MANAGE_EVENTS), async (req, res) => {
  // req.org, req.orgMember set
});

​

Routes

​

Structure

• Routes live in Meridian/backend/routes/ (and under Meridian/backend/events/routes/ for event features).
• Each file exports an Express Router. Mount in app.js (or in events/index.js for event routes).
• Prefer middleware + single handler per path; keep handlers thin and delegate to services when logic is non-trivial.

​

Response shape

​

Protected vs public

• Protected: Put verifyToken (and optionally authorizeRoles or org permission middlewares) in the route chain. Then you can use req.user and getModels(req, ...).
• Public: Do not use verifyToken. For optional auth (e.g. personalized data when logged in), use verifyTokenOptional.

​

Services

• Location: Meridian/backend/services/
• Role: Encapsulate business logic, external APIs, and shared helpers. Keep route handlers focused on HTTP and validation.
• DB access: If a service needs DB, the caller (route or other service) must pass req. The service then calls getModels(req, 'ModelName', ...) and uses the returned models. Example: userServices.js, studySessionService.js.
• No req in context: For background jobs or scripts without req, obtain a Mongoose connection and pass something that has a db property (or refactor to accept a connection/model factory) so tenant and model resolution still work. Do not introduce a global default connection for app data.

​

Events submodule

• Mount: Meridian/backend/events/index.js is required in app.js and mounted as app.use(eventsRoutes).
• Routes: Under Meridian/backend/events/routes/ (e.g. eventSystemConfigRoutes.js, analyticsRoutes.js). These are aggregated in events/index.js.
• Schemas: Event-related schemas live in Meridian/backend/events/schemas/. They are required and registered in getModelService.js; event routes and middlewares use the same getModels(req, ...) pattern.

​

Permissions constants

• File: Meridian/backend/constants/permissions.js
• Exports: ORG_PERMISSIONS, EVENT_PERMISSIONS, USER_PERMISSIONS, SYSTEM_PERMISSIONS, PERMISSION_GROUPS, PERMISSION_DESCRIPTIONS, plus helpers like getPermissionDescription, validatePermission.
• Usage: Use these constants instead of string literals when checking or assigning permissions (e.g. in requireOrgPermission(ORG_PERMISSIONS.MANAGE_EVENTS)). This keeps permission names consistent and refactor-safe.

​

Conventions summary

​

Known inconsistencies and gotchas

• Duplicate key in getModelService: The models object in getModelService.js defines EventAnalytics twice (same schema/collection). Prefer a single entry to avoid confusion.
• Token expiry: verifyToken.js and authRoutes.js use different ACCESS_TOKEN_EXPIRY values (e.g. 15m vs 1m). Align these in one place (e.g. a shared auth constants file) so middleware and token issuance stay in sync.
• verifyTokenOptional: Uses a callback-style jwt.verify and calls next() from inside the callback; ensure next() is never called twice (e.g. on refresh path) to avoid double-response issues.
• StudySession service: studySessionService.js expects req and calls getModels(req, ...). Any caller must pass the real req from the route.

​

Quick reference: key files

​

Related pages