Schema Design

Step 3 — Define Schema with Types, Validation, and Indexes

• Use explicit Mongoose types (String, Number, ObjectId, Date, Boolean, [SubSchema]).
• Add required, enum, minlength, maxlength, min, max, match validators as needed.
• Define compound indexes for frequent query patterns.
• Add unique indexes where business rules demand it.
• Use sparse indexes for optional unique fields.

Step 4 — Create Model File

• Place the file in src/models/<EntityName>.js (or .ts).
• Export the model as a named export: module.exports = mongoose.model('EntityName', entitySchema);.
• Keep one model per file.

Step 5 — Add Timestamps and Virtuals

• Enable { timestamps: true } for automatic createdAt / updatedAt.
• Add virtuals for computed fields (e.g., fullName from firstName + lastName).
• Set toJSON: { virtuals: true } and toObject: { virtuals: true } in schema options.

Step 6 — Document Schema Decisions

• Add a JSDoc block at the top of the model file describing the collection purpose.
• Note embedding/referencing decisions and why.
• If the schema is non-trivial, add an entry to architecture/ as an ADR.
• Update state/STATE.md with the new or modified model.

Checklist

• All fields have explicit types and required validators where appropriate.
• Indexes match the most common query patterns.
• Embed vs reference decision is documented.
• Timestamps enabled.
• Model file lives in src/models/.
• state/STATE.md updated.