Skip to content

Commit 4f54b2f

Browse files
beginwebdev2002beginwebdev2002
authored
Merge pull request #28 from beginwebdev2002/feat/backend-mongodb-docs-9507427399526486300
Initialize specialized documentation for MongoDB
2 parents 64f1248 + be09a6c commit 4f54b2f

5 files changed

Lines changed: 412 additions & 0 deletions

File tree

‎backend/mongodb/architecture.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
description: Vibe coding guidelines and architectural constraints for MongoDB within the backend domain.
3+
technology: MongoDB
4+
domain: backend
5+
level: Senior/Architect
6+
complexity: Advanced
7+
topic: MongoDB Architecture
8+
vibe_coding_ready: true
9+
version: "7.0+"
10+
tags: [architecture-patterns, mongodb, nosql, database, system-design, production-ready, scalable-code]
11+
ai_role: Senior MongoDB Database Architect
12+
last_updated: 2026-03-28
13+
last_evolution: 2026-03-28
14+
---
15+
16+
# 🏛️ MongoDB Architecture Constraints
17+
18+
This document provides the "executable blueprints" for MongoDB architecture, outlining folder hierarchies, request/data flows, and entity relationships to ensure AI-agent readiness.
19+
20+
## 📂 Folder Hierarchy Constraints
21+
22+
```mermaid
23+
graph TD
24+
classDef domain fill:#f9f,stroke:#333,stroke-width:2px;
25+
classDef core fill:#bbf,stroke:#333,stroke-width:2px;
26+
27+
src[src] --> domains[domains]
28+
src --> core[core]
29+
30+
domains --> user[User Domain]
31+
domains --> order[Order Domain]
32+
33+
user --> schemas[schemas/]
34+
user --> models[models/]
35+
user --> repositories[repositories/]
36+
37+
core --> database[database/]
38+
database --> connection[connection.ts]
39+
database --> config[config.ts]
40+
41+
class domains,user,order,schemas,models,repositories domain;
42+
class core,database,connection,config core;
43+
```
44+
45+
## 🔄 Request / Data Flow
46+
47+
```mermaid
48+
sequenceDiagram
49+
participant Client
50+
participant Controller
51+
participant Service
52+
participant Repository
53+
participant Database
54+
55+
Client->>Controller: POST /api/users (DTO)
56+
Controller->>Service: Create User (Domain Model)
57+
Service->>Repository: Save User (Entity)
58+
Repository->>Database: insertOne()
59+
Database-->>Repository: Acknowledgment (ObjectId)
60+
Repository-->>Service: Saved Entity
61+
Service-->>Controller: Domain Response
62+
Controller-->>Client: 201 Created (Response DTO)
63+
```
64+
65+
## 🔗 Entity Relationships
66+
67+
```mermaid
68+
classDiagram
69+
class User {
70+
+ObjectId _id
71+
+String username
72+
+String email
73+
+String passwordHash
74+
+Date createdAt
75+
+Date updatedAt
76+
+login()
77+
+updateProfile()
78+
}
79+
80+
class Post {
81+
+ObjectId _id
82+
+ObjectId authorId
83+
+String title
84+
+String content
85+
+Array~ObjectId~ tags
86+
+Date publishedAt
87+
}
88+
89+
class Comment {
90+
+ObjectId _id
91+
+ObjectId postId
92+
+ObjectId authorId
93+
+String text
94+
+Date createdAt
95+
}
96+
97+
User "1" --> "*" Post : creates
98+
User "1" --> "*" Comment : writes
99+
Post "1" --> "*" Comment : contains
100+
```
101+
102+
---
103+
104+
[⬆ Back to Top](#-mongodb-architecture-constraints)

‎backend/mongodb/database-optimization.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
description: Vibe coding guidelines and database optimization constraints for MongoDB within the backend domain.
3+
technology: MongoDB
4+
domain: backend
5+
level: Senior/Architect
6+
complexity: Advanced
7+
topic: MongoDB Database Optimization
8+
vibe_coding_ready: true
9+
version: "7.0+"
10+
tags: [database-optimization, mongodb, nosql, indexing, aggregation-pipeline, system-design, production-ready, scalable-code]
11+
ai_role: Senior MongoDB Database Architect
12+
last_updated: 2026-03-28
13+
last_evolution: 2026-03-28
14+
---
15+
16+
# ⚡ MongoDB Database Optimization Best Practices
17+
18+
This document outlines indexing strategies (ESR Rule), aggregation pipeline optimization, and query tuning for enterprise-grade MongoDB environments.
19+
20+
## 🎯 1. The ESR (Equality, Sort, Range) Rule
21+
22+
When designing indexes, always follow the ESR rule to maximize efficiency.
23+
24+
### ❌ Bad Practice
25+
26+
Creating indexes randomly without understanding the query patterns.
27+
28+
```javascript
29+
// A query with equality, sort, and range:
30+
// db.orders.find({ status: "shipped", amount: { $gt: 100 } }).sort({ date: 1 })
31+
32+
// Bad index - Range comes before Sort
33+
db.orders.createIndex({ status: 1, amount: 1, date: 1 })
34+
```
35+
36+
### ✅ Best Practice
37+
38+
Create indexes following the ESR rule:
39+
1. **E**quality fields first.
40+
2. **S**ort fields next.
41+
3. **R**ange fields last.
42+
43+
### 🚀 Solution
44+
45+
```javascript
46+
// Ideal index for the ESR query
47+
db.orders.createIndex({ status: 1, date: 1, amount: 1 })
48+
```
49+
50+
---
51+
52+
## 🏗️ 2. Aggregation Pipeline Optimization
53+
54+
Pipelines process documents in stages. Optimizing the order of these stages dramatically improves performance.
55+
56+
### ❌ Bad Practice
57+
58+
Filtering data after heavy transformations or sorting large un-indexed datasets.
59+
60+
```javascript
61+
db.users.aggregate([
62+
{ $project: { name: 1, age: 1, status: 1 } },
63+
{ $sort: { age: -1 } },
64+
{ $match: { status: "active" } }
65+
])
66+
```
67+
68+
### ✅ Best Practice
69+
70+
Always use `$match` and `$sort` as early as possible in the pipeline to reduce the working set and take advantage of indexes. Use `$project` later.
71+
72+
### 🚀 Solution
73+
74+
```javascript
75+
db.users.aggregate([
76+
{ $match: { status: "active" } },
77+
{ $sort: { age: -1 } },
78+
{ $project: { name: 1, age: 1 } }
79+
])
80+
```
81+
82+
---
83+
84+
## 📉 3. Covered Queries
85+
86+
A covered query is a query that can be satisfied entirely using an index, without having to examine the actual documents.
87+
88+
### 🚀 Solution
89+
90+
If you have an index on `{ status: 1, amount: 1 }`:
91+
92+
```javascript
93+
// This is a covered query because it only projects indexed fields (and explicitly excludes _id)
94+
db.orders.find(
95+
{ status: "shipped" },
96+
{ status: 1, amount: 1, _id: 0 }
97+
)
98+
```
99+
100+
---
101+
102+
[⬆ Back to Top](#-mongodb-database-optimization-best-practices)

‎backend/mongodb/readme.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
description: Vibe coding guidelines and architectural constraints for MongoDB within the backend domain.
3+
technology: MongoDB
4+
domain: backend
5+
level: Senior/Architect
6+
complexity: Advanced
7+
topic: MongoDB
8+
vibe_coding_ready: true
9+
version: "7.0+"
10+
tags: [best-practices, clean-code, architecture-patterns, vibe-coding, mongodb, nosql, database, system-design, production-ready, scalable-code, document-database]
11+
ai_role: Senior MongoDB Database Architect
12+
last_updated: 2026-03-28
13+
last_evolution: 2026-03-28
14+
---
15+
16+
<div align="center">
17+
<img src="https://raw.githubusercontent.com/tandpfun/skill-icons/main/icons/MongoDB.svg" width="100" alt="MongoDB Logo">
18+
19+
# 🍃 MongoDB Production-Ready Best Practices
20+
</div>
21+
22+
---
23+
24+
This document establishes **best practices** for building and maintaining MongoDB databases. These constraints guarantee a scalable, highly secure, and clean architecture suitable for an enterprise-level, production-ready backend.
25+
26+
# ⚙️ Context & Scope
27+
- **Primary Goal:** Provide an uncompromising set of rules and architectural constraints for MongoDB environments.
28+
- **Target Tooling:** AI-agents (Cursor, Windsurf, Copilot, Antigravity) and Senior Database Administrators.
29+
- **Tech Stack Version:** MongoDB 7.0+
30+
31+
> [!IMPORTANT]
32+
> **Architectural Contract:** MongoDB is schema-less by nature, but production applications require strict schema validation at the database level and through ORM/ODMs like Mongoose. Never allow unstructured data to enter the persistence layer without validation.
33+
34+
---
35+
36+
## 📚 Specialized Documentation
37+
38+
For deep dives into specific topics, consult the specialized guides:
39+
40+
- 🏛️ [**Architecture & Design**](./architecture.md): Boundary definitions, entity relationships, and structural constraints.
41+
- ⚡ [**Database Optimization**](./database-optimization.md): Indexing strategies (ESR Rule) and aggregation pipelines.
42+
- 🔒 [**Security Best Practices**](./security-best-practices.md): RBAC, field-level encryption, and NoSQL injection prevention.
43+
44+
---
45+
46+
## 🏗️ Core Principles
47+
48+
### 🚨 1. Schema Validation
49+
#### ❌ Bad Practice
50+
```javascript
51+
// Inserting data without validation
52+
db.users.insertOne({ name: "John", age: -5, admin: true });
53+
```
54+
#### ✅ Best Practice
55+
Implement strict schema validation using JSON Schema in MongoDB.
56+
#### 🚀 Solution
57+
```javascript
58+
db.createCollection("users", {
59+
validator: {
60+
$jsonSchema: {
61+
bsonType: "object",
62+
required: ["name", "email"],
63+
properties: {
64+
name: {
65+
bsonType: "string",
66+
description: "must be a string and is required"
67+
},
68+
email: {
69+
bsonType: "string",
70+
pattern: "^.+@.+\\..+$",
71+
description: "must be a valid email and is required"
72+
},
73+
age: {
74+
bsonType: "int",
75+
minimum: 0,
76+
description: "must be an integer greater than or equal to 0"
77+
}
78+
}
79+
}
80+
}
81+
});
82+
```
83+
84+
---
85+
86+
[⬆ Back to Top](#-mongodb-production-ready-best-practices)

0 commit comments

Comments
 (0)