STACK IT FAST
ALL RULES & SKILLS

Node.js + Express + MongoDB

Raw .MD node-express-mongodb
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

Production guidelines for Express REST APIs, Mongoose schema design, and MongoDB indexing/transaction discipline.

Node.js Express MongoDB TypeScript Redis
CLI & AI Agent Import Verified in 4 production projects
AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/node-express-mongodb
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
AGENTS.md·37 lines · 3.6 KB
1# Project Architecture & Guidelines (Node.js + Express + MongoDB)
2
3## 1. System Architecture
4- **Runtime**: Node.js (TypeScript, `ts-node`/`tsx` for dev, compiled output for production).
5- **Web Framework**: Express 4/5 for REST API routing and middleware.
6- **Database**: MongoDB with Mongoose for schema definition, validation, and typed models.
7- **Caching/Queues**: Redis for session storage, caching, and BullMQ-backed background jobs.
8
9## 2. Mongoose Schema & Validation
10- Define explicit schemas with Mongoose (`new Schema({...}, { timestamps: true })`) even though MongoDB is schemaless at the database level — untyped documents are the single largest source of bugs in Node/Mongo codebases.
11- Use Mongoose's built-in validators (`required`, `enum`, custom `validate` functions) as the first line of defense; add a Zod schema at the API boundary for request-shape validation before it reaches Mongoose.
12- Prefer embedding for data that's always read together and rarely grows unbounded (a project's settings object); reference (`ObjectId` + `ref`) for data that's queried independently or grows without bound (a project's activity log).
13
14## 3. Indexing & Query Discipline
15- Every field used in a `find()` filter, sort, or unique constraint needs an explicit index (`schema.index({ projectId: 1, createdAt: -1 })`) — MongoDB does not warn about missing indexes, it just degrades to a full collection scan.
16- Use `.lean()` on read-only queries that don't need Mongoose document methods; it skips hydration overhead and meaningfully reduces memory/CPU on hot read paths.
17- Avoid unbounded `.find({})` without pagination (`.limit()`/`.skip()` or cursor-based pagination) on any collection that can grow past a few thousand documents.
18
19## 4. Transactions & Data Consistency
20- Use MongoDB multi-document transactions (`session.startTransaction()`) for any write that spans more than one collection and must be atomic (e.g. deducting credits and creating a record) — MongoDB supports ACID transactions on replica sets, this isn't a "NoSQL means no transactions" situation.
21- Transactions require a replica set (even a single-node one in development); configure this explicitly rather than discovering it's missing when a transaction call throws in production.
22
23## 5. Common Pitfalls / Coding Standards
24- ❌ Querying without an index on a collection expected to grow — profile with `.explain('executionStats')` before shipping a new query pattern.
25- ❌ Deeply nested embedded arrays that grow unbounded (MongoDB documents have a 16MB size limit).
26- ✅ Use `.lean()` for read-heavy endpoints; reserve hydrated Mongoose documents for paths that call instance methods or need change tracking.
27
28## 6. Testing Conventions
29- Vitest/Jest with `mongodb-memory-server` for fast, isolated integration tests against a real (in-memory) MongoDB instance rather than mocking Mongoose.
30- Supertest for Express route-level tests, asserting status codes and response shape.
31- Test index usage explicitly for any query on a collection expected to scale, via `.explain()` assertions in CI if query performance regressions have happened before.
32
33## 7. Git Workflow & PR Conventions
34- Conventional Commits scoped to the resource, e.g. `perf(projects): add compound index for owner+status filter`.
35- New indexes ship in the same PR as the query pattern that needs them, with a migration/init script that creates them idempotently (`createIndexes` is safe to re-run).
36- Require `tsc --noEmit` and the test suite green before merge.
37- Squash-merge; run index creation as an explicit deploy step on large collections (it can lock or slow the collection during build).
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

Architecture Overview

Standardized production guidelines for Node.js, Express, and MongoDB via Mongoose — the default choice when a project’s data is naturally document-shaped (chat messages, notification payloads, flexible per-tenant configuration) rather than relational.

Verified Real-World Adoption

LibreChat (multi-model AI chat workspace) and Novu (notification infrastructure) both run Node.js/TypeScript + MongoDB in production, and Rocket.Chat uses the same combination for its real-time team communications platform.

Key Architectural Nuances

  • Schemas Matter Even on a Schemaless Database: Mongoose schemas plus a Zod boundary layer are what actually prevent the “any shape of document can end up in this collection” failure mode that gives MongoDB its reputation for bugs.
  • Indexes Are Opt-In, Not Automatic: Unlike a well-tuned PostgreSQL setup that at least logs slow queries, MongoDB will silently full-scan an unindexed filter forever — index discipline has to be deliberate, not reactive.
FREQUENTLY ASKED QUESTIONS

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Does MongoDB actually support transactions?

Yes, since MongoDB 4.0, multi-document ACID transactions are supported on replica sets (including a single-node replica set in development). The common misconception that MongoDB can't do transactions dates to pre-4.0 versions; as of any current deployment, if an operation needs to atomically touch more than one document or collection, a session-based transaction is the correct tool, not application-level compensating logic.

When should a field be embedded versus referenced with an ObjectId?

Embed when the data is always fetched together with its parent and has a bounded size (a user's address, a project's settings). Reference when the data is queried independently of its parent, grows without a practical bound (comments, activity logs), or is shared across multiple parent documents. Getting this wrong in the embed direction is how documents hit the 16MB size limit.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills
4 FILE FORMATS Django, Python

Django + PostgreSQL + Redis + Celery

Production guidelines for Django 5 enterprise applications, PostgreSQL connection pooling, Redis caching, and Celery async workers.

6 techs Copy Rules
4 FILE FORMATS FastAPI, Python

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Production guidelines for FastAPI, Pydantic v2 validation, Async SQLAlchemy 2.0 (asyncpg), Alembic migrations, and PostgreSQL/Redis.

7 techs Copy Rules
4 FILE FORMATS LangGraph, LangChain

LangGraph + Python + FastAPI (Agentic AI Workflows)

Production architecture for autonomous multi-agent systems, LangGraph cyclic state graphs, Pydantic v2 structured tool calling, and Chroma/Qdrant vector stores.

6 techs Copy Rules
4 FILE FORMATS Laravel, Livewire

Laravel + Livewire + PostgreSQL

Production guidelines for Laravel 11 monoliths, Livewire reactive components, Eloquent ORM query discipline, and queued job workers.

6 techs Copy Rules