Imported from DevangSaini19/Library-Management-System (AGENTS.md). Install upstream with npx skills add DevangSaini19/Library-Management-System. Copyright stays with the author.

AGENTS.md

Guidance for AI coding agents working in this repository.

A MEAN-stack (MongoDB, Express, Angular, Node.js) library app used in MongoDB Developer Days workshops. The server (server/) exposes a REST API backed by MongoDB Atlas; the client (client/) is an Angular SPA that consumes it.

Build and test commands

npm run setup                     # root: installs root + server + client deps and creates server/.env
npm run db:start                  # local MongoDB 8 in Docker (docker compose up -d mongodb)
npm run db:seed                   # load .devcontainer/data/library/*.bson into DATABASE_NAME
npm run dev                       # server (5400) + Angular dev server (4200) together
npm run build                     # tsc + ng build
npm run lint                      # eslint over server/src
npm test                          # server API tests (needs a reachable MongoDB)

npm install                       # root only: husky for the pre-commit hook
cd server && npm install          # server dependencies
cd client && npm install          # client dependencies

cd server && npm run build:watch  # compile TypeScript, watch mode
cd server && npm run serve        # run compiled server with nodemon
cd server && npm start            # build:watch + serve together (typical dev loop)
cd server && npm run lint         # eslint src/
cd server && npm run api-test     # mocha, requires a running server + MongoDB
cd server && npm test             # starts the server, waits for it, then runs api-test

cd client && npm start            # ng serve on http://localhost:4200
cd client && npm run build        # ng build
cd client && npm test             # ng test (Karma)

The pre-commit hook (.husky/pre-commit) starts the mongodb service from the root docker-compose.yml (a local MongoDB), then runs npm run lint and npm test inside server/. When Docker is not installed the hook only lints, so git commit still works outside of Codespaces/the devcontainer; git commit --no-verify skips it entirely.

Smoke check after a change:

1. Run the commands above to start server (port 5400) and client (port 4200).
2. Open http://localhost:4200 and confirm the book list loads.
3. Log in, borrow or reserve a book, and confirm the change is reflected in the UI.

Project structure

server/src/
  server.ts            # Express app entry point, route mounting
  database.ts          # MongoDB client/connection, collection handles
  load-env-vars.ts      # dotenv bootstrap, imported first in every entry point
  models/              # TypeScript interfaces for each collection's documents
  routes/              # Express routers (one per resource) plus *.spec.ts API tests
  controllers/         # Request handlers used by routes/
  utils/               # Auth middleware, shared test helpers
  embeddings/           # Pluggable embedding providers (OpenAI, Google Vertex, a
                         # serverless endpoint) selected via EMBEDDINGS_SOURCE
  search-indexing/      # Standalone scripts that create/update MongoDB Search and
                         # Vector Search indexes on the books collection (workshop labs)
  indexing/             # Standalone script demonstrating a compound index via .explain()
client/src/app/         # Angular components, services, routing
scripts/                # Root-level dev tooling: setup-env.mjs (creates server/.env from the
                        # template) and seed.mjs (imports the sample .bson dump with the Node
                        # driver only — no MongoDB Database Tools required). Exposed as
                        # `npm run setup` / `npm run db:seed`.
docker-compose.yml      # Local MongoDB for development (`npm run db:start` / `db:stop`)
migrations/             # One-off data migration scripts (run manually with Node)
.devcontainer/          # Codespaces/Dev Containers setup: local Atlas container,
                         # sample data import, port forwarding, best-effort
                         # created/started lifecycle telemetry (track.sh)

Notable files:

• server/src/database.ts — throws a descriptive error if DATABASE_URI is unset or still the placeholder value; read this first when the server won't start.
• server/src/models/issue-detail.ts — a single collection (issueDetails) holds both borrowed-book and reservation records, distinguished by recordType.
• server/src/search-indexing/*.ts — each file is a runnable workshop step (node --loader ts-node/esm src/search-indexing/<file>.ts after building) that creates one MongoDB Search/MongoDB Vector Search index variant. Several contain <REPLACE_WITH_...> placeholders left in on purpose for the workshop exercise — do not "fix" them as bugs.

API overview

Environment variables and configuration

server/.env is git-ignored and must be created locally — npm run setup copies it from server/.env.example, which ships with working local defaults (mongodb://127.0.0.1:27017, database library). Never commit a real Atlas credential.

server/src/load-env-vars.ts resolves .env relative to itself (not the cwd) and the root scripts/seed.mjs reads the same file, so any entry point — npm start, nodemon, node dist/server.js, a debugger — picks up the same configuration.

Constraints worth knowing before you debug a failure:

• connectToDatabase throws immediately if DATABASE_URI is missing or equals the literal placeholder mongodb+srv://user:password@cluster — check that error message before assuming the driver itself is failing.
• The MongoDB client is created with appName: 'devrel-workshop-node-angular-library' (server/src/database.ts), so Atlas-side connection metrics for this app are distinguishable from other Developer Days workshop repos.
• server/test (via start-server-and-test) boots a real server against DATABASE_NAME=testLibrary on port 5200 and runs api-test against it — it needs a reachable MongoDB, same as normal dev.

MongoDB Skills

Use the official MongoDB agent skills from https://github.com/mongodb/agent-skills whenever the task is MongoDB-specific and a matching skill exists.

When To Use EDD.md

Use EDD.md as the source of truth for the MongoDB data model in this repository.

Consult EDD.md before making changes that touch:

• MongoDB collections, document structure, or field names
• Express routes that read or write database records
• Validation, form fields, API payloads, or UI that depend on persisted data
• Schema documentation, Mermaid diagrams, or entity modeling discussions