1. Server setup:

Import packages
     ↓
Create Express app
     ↓
Add middleware
     ↓
Connect database
     ↓
Create auth/helpers
     ↓
Create routes/controllers
     ↓
Start server

When a request arrives:

CLIENT
  ↓
REQUEST
  ↓
MIDDLEWARE
  ↓
CONTROLLER
  ↓
DATABASE
  ↓
RESPONSE

2. Importing Packages

const express = require('express');
const mongoose = require('mongoose');
const jwt = require('jsonwebtoken');

• Express → creates the backend/server.

• Mongoose → communicates with MongoDB.

• jsonwebtoken → creates and verifies JWTs.

Node.js → Express → Server
Node.js → Mongoose → MongoDB
Node.js → JWT → Authentication

3. Importing Our Own Models

const User = require('./User');
const Client = require('./Client');

./User means:

Go to User.js and give me what that file exports.

The models define how our MongoDB data is structured.

4. Creating the Express App

const app = express();

express() creates an Express application.

We store it in app, which is why we can use:

app.get(...)
app.post(...)
app.use(...)
app.listen(...)

Think:

express()
   ↓
Express application
   ↓
app

5. JSON Middleware

app.use(express.json());

If Postman sends:

{
    "bio": "I am learning backend"
}

express.json() parses it so we can access:

req.body

Therefore:

JSON request
    ↓
express.json()
    ↓
req.body

6. Connecting MongoDB

await mongoose.connect(
    'mongodb://127.0.0.1:27017/backendPractice'
);

Meaning:

127.0.0.1 → this computer
27017      → MongoDB port
backendPractice → database name

A clean startup flow is:

startServer()
     ↓
connect MongoDB
     ↓
successful?
   ↙       ↘
 yes       no
 ↓         ↓
listen    error

So the server starts accepting requests only after the database connection succeeds.

7. .then() and .catch()

For a promise:

mongoose.connect(...)
    .then(() => {
        console.log('Connected');
    })
    .catch((error) => {
        console.log(error);
    });

Think:

Try operation
   ↓
 ┌───────┴───────┐
success         failure
   ↓               ↓
 then            catch

8. Middleware

Middleware sits between the request and the controller.

REQUEST
   ↓
middleware
   ↓
controller
   ↓
response

It receives:

(req, res, next)

• req → incoming request

• res → response

• next → continue to the next step

Middleware can:

• authenticate

• validate

• log

• modify req

• block requests

9. req.params, req.body, req.headers

These are three important sources of request information.

req.params

For:

app.get('/generate-token/:userId', ...)

Request:

/generate-token/ABC123

Then:

req.params.userId

is:

ABC123

Used for values inside the URL.

req.body

For:

{
    "bio": "Hello"
}

we get:

req.body.bio

Used for data sent inside the request body.

req.headers

For:

Authorization: Bearer XYZ...

we can access:

req.headers.authorization

Used for request metadata such as authentication information.

10. Getting the JWT

const token =
    req.headers.authorization?.split(' ')[1];

Suppose:

Bearer eyJhb...

After:

.split(' ')

we get:

["Bearer", "eyJhb..."]

[1] gives:

eyJhb...

So the flow is:

Authorization header
       ↓
"Bearer TOKEN"
       ↓
split(' ')
       ↓
["Bearer", "TOKEN"]
       ↓
[1]
       ↓
TOKEN

11. Optional Chaining ?.

Without:

authorization.split(' ')

if authorization doesn't exist, JavaScript can crash.

With:

authorization?.split(' ')

JavaScript says:

If it exists, continue. Otherwise give undefined.

Use ?. when something may legitimately be missing.

It is different from try/catch:

?.         → safely access missing value
try/catch → handle an operation that throws

12. Authentication Middleware

A simple authentication flow:

const auth = (req, res, next) => {

    const token =
        req.headers.authorization?.split(' ')[1];

    if (!token) {
        return res.status(401).json({
            message: 'No token provided'
        });
    }

    try {
        const decoded = jwt.verify(
            token,
            'mysecretkey'
        );

        req.user = decoded;

        next();

    } catch (error) {
        return res.status(401).json({
            message: 'Invalid token'
        });
    }
};

The mental model:

Request
   ↓
Get token
   ↓
Token exists?
   ↓
Verify JWT
   ↓
Valid?
 ↙     ↘
NO      YES
↓        ↓
401    req.user
         ↓
       next()

13. Why req.user = decoded?

Suppose the JWT contains:

{
    userId: "12345"
}

After verification:

req.user = decoded;

Now later code can use:

req.user.userId

The flow is:

JWT
 ↓
verify
 ↓
decoded data
 ↓
req.user
 ↓
controller

14. Why next()?

next() means:

Authentication succeeded. Continue the request pipeline.

If authentication fails:

return res.status(401).json(...)

The request stops.

If authentication succeeds:

next();

The request continues.

Think of middleware as a security checkpoint:

Request
   ↓
Security check
   ↓
 ┌───────┴───────┐
fail            success
 ↓                 ↓
STOP              next()

15. Helper Functions

Example:

const formatClient = (client) => {
    return {
        savedLawyers: client.savedLawyers,
        blockedLawyers: client.blockedLawyers,
        bio: client.bio
    };
};

A helper takes existing data and creates the format we want to send.

MongoDB document
      ↓
formatClient()
      ↓
clean response

This prevents us from sending unnecessary fields.

16. Controller

Example:

app.get('/api/client/profile', auth, async (req, res) => {
    ...
});

There are three parts:

/api/client/profile → URL
auth                → middleware
async (req, res)    → controller logic

The controller answers:

What should happen when this endpoint is called?

For a profile request:

Get user ID
    ↓
Find User
    ↓
Find Client
    ↓
Format data
    ↓
Send response

17. Finding User and Client

const id = req.user.userId;

const user = await User.findOne({
    _id: id
});

const client = await Client.findOne({
    userId: id
});

The User has:

_id = 12345

The Client has:

userId = 12345

So they are connected:

USER
_id = 12345
    ↑
    │
CLIENT
userId = 12345

If either doesn't exist:

if (!user) {
    return res.status(404).json({
        message: 'User not found'
    });
}

18. Sending Response

return res.status(200).json({
    userProfile: formatUser(user),
    clientProfile: formatClient(client)
});

200 means the request succeeded.

The response is sent back to Postman/frontend.

19. try/catch in Controllers

Database operations can throw errors:

try {
    const user = await User.findOne(...);
}
catch (error) {
    res.status(500).json({
        message: 'Server error'
    });
}

Think:

Expected problem
     ↓
if check
     ↓
401 / 404 / etc.

Unexpected thrown error
     ↓
try/catch
     ↓
500

20. Updating Profile

app.put('/api/client/profile', auth, async (req, res) => {
    ...
});

Remember:

GET → retrieve
PUT → update

Example:

const client = await Client.findOneAndUpdate(
    { userId: id },
    { bio: req.body.bio },
    { new: true }
);

Three objects:

1. What to find

{ userId: id }

2. What to change

{ bio: req.body.bio }

3. What to return

{ new: true }

new: true means:

Return the updated document instead of the old one.

21. JWT Creation

const token = jwt.sign(
    { userId: req.params.userId },
    'mysecretkey',
    { expiresIn: '1h' }
);

This creates a JWT containing:

{
    userId: "ABC123"
}

with:

secret → mysecretkey
expiry → 1 hour

Then:

res.json({
    token: token
});

sends it to the client.

The client can later send:

Authorization: Bearer TOKEN

22. Middleware vs Controller

This is the important distinction.

Ask:

Is this checking/preparing something before the actual operation?

If yes → middleware

Ask:

Is this actually performing what the endpoint was requested to do?

If yes → controller

Middleware

Check authentication
Check permissions
Validate
Prepare request
   ↓
next()

Controller

Perform endpoint's job
   ↓
Database
   ↓
Business logic
   ↓
Response

For example:

GET /profile
     ↓
    auth          ← middleware
     ↓
getProfile        ← controller
     ↓
 MongoDB
     ↓
 response

23. Complete Mental Model

Whenever you read Express code, ask:

1. Where did the information come from?
   ↓
params / body / query / headers

2. What needs to be checked first?
   ↓
middleware

3. What is this endpoint supposed to do?
   ↓
controller

4. Where does the data come from/go?
   ↓
database

5. What do we send back?
   ↓
response

The whole backend can therefore be understood as:

REQUEST
   ↓
Where is the data?
(params/body/headers)
   ↓
MIDDLEWARE
(check/prepare/block)
   ↓
CONTROLLER
(actual endpoint work)
   ↓
DATABASE
   ↓
RESPONSE

Express backend code is essentially a request entering the system, passing through checkpoints, performing an operation, talking to the database, and finally returning a response.

HOW TO STRUCTURE THE SAME FOR A LARGE PROJECT

server/
│
├── server.js
├── package.json
├── .env
│
├── config/
│   ├── db.js
│   └── env.js
│
├── models/
│   ├── User.js
│   └── Client.js
│
├── controllers/
│   ├── auth.controller.js
│   └── client.controller.js
│
├── routes/
│   ├── auth.routes.js
│   └── client.routes.js
│
├── middleware/
│   ├── auth.middleware.js
│   ├── error.middleware.js
│   └── validation.middleware.js
│
├── services/
│   ├── auth.service.js
│   └── client.service.js
│
├── utils/
│   ├── jwt.js
│   ├── formatters.js
│   └── asyncHandler.js
│
└── validators/
    ├── auth.validator.js
    └── client.validator.js

server.js

const express = require('express');

const connectDB = require('./config/db');

const authRoutes = require('./routes/auth.routes');
const clientRoutes = require('./routes/client.routes');

const errorHandler = require('./middleware/error.middleware');

const app = express();

app.use(express.json());

connectDB();

app.use('/api/auth', authRoutes);
app.use('/api/client', clientRoutes);

app.get('/', (req, res) => {
    res.json({
        message: 'Server is running'
    });
});

app.use(errorHandler);

app.listen(5000, () => {
    console.log('Server running on http://localhost:5000');
});

config/db.js

const mongoose = require('mongoose');

const connectDB = async () => {
    try {
        await mongoose.connect(
            'mongodb://127.0.0.1:27017/backendPractice'
        );

        console.log('MongoDB connected');
    } catch (error) {
        console.log('MongoDB connection failed');
        console.log(error);
    }
};

module.exports = connectDB;

models/User.js

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
    name: String,
    email: String,
    phone: String,
    role: String,
    isEmailVerified: Boolean,
    isPhoneVerified: Boolean,
    isActive: Boolean
});

module.exports = mongoose.model('User', userSchema);

models/Client.js

const mongoose = require('mongoose');

const clientSchema = new mongoose.Schema({
    userId: {
        type: mongoose.Schema.Types.ObjectId,
        ref: 'User'
    },

    savedLawyers: [
        {
            type: mongoose.Schema.Types.ObjectId
        }
    ],

    blockedLawyers: [
        {
            type: mongoose.Schema.Types.ObjectId
        }
    ],

    bio: String
});

module.exports = mongoose.model('Client', clientSchema);

middleware/auth.middleware.js

const jwt = require('jsonwebtoken');

const auth = (req, res, next) => {
    const token = req.headers.authorization?.split(' ')[1];

    if (!token) {
        return res.status(401).json({
            message: 'No token provided'
        });
    }

    try {
        const decoded = jwt.verify(
            token,
            'mysecretkey'
        );

        req.user = decoded;

        next();

    } catch (error) {
        return res.status(401).json({
            message: 'Invalid token'
        });
    }
};

module.exports = auth;

middleware/error.middleware.js

const errorHandler = (error, req, res, next) => {
    console.log(error);

    res.status(500).json({
        message: 'Server error'
    });
};

module.exports = errorHandler;

utils/formatters.js

const formatClient = (client) => {
    return {
        savedLawyers: client.savedLawyers,
        blockedLawyers: client.blockedLawyers,
        bio: client.bio
    };
};

const formatUser = (user) => {
    return {
        name: user.name,
        email: user.email,
        phone: user.phone,
        role: user.role,
        isEmailVerified: user.isEmailVerified,
        isPhoneVerified: user.isPhoneVerified,
        isActive: user.isActive
    };
};

module.exports = {
    formatClient,
    formatUser
};

utils/jwt.js

const jwt = require('jsonwebtoken');

const generateToken = (userId) => {
    return jwt.sign(
        {
            userId: userId
        },
        'mysecretkey',
        {
            expiresIn: '1h'
        }
    );
};

module.exports = {
    generateToken
};

utils/asyncHandler.js

const asyncHandler = (fn) => {
    return (req, res, next) => {
        Promise
            .resolve(fn(req, res, next))
            .catch(next);
    };
};

module.exports = asyncHandler;

controllers/client.controller.js

const User = require('../models/User');
const Client = require('../models/Client');

const {
    formatClient,
    formatUser
} = require('../utils/formatters');

const asyncHandler = require('../utils/asyncHandler');

const getMyProfile = asyncHandler(async (req, res) => {

    const id = req.user.userId;

    const user = await User.findOne({
        _id: id
    });

    const client = await Client.findOne({
        userId: id
    });

    if (!user) {
        return res.status(404).json({
            message: 'User not found'
        });
    }

    if (!client) {
        return res.status(404).json({
            message: 'Client not found'
        });
    }

    const formattedUser = formatUser(user);
    const formattedClient = formatClient(client);

    return res.status(200).json({
        userProfile: formattedUser,
        clientProfile: formattedClient
    });
});

const updateProfile = asyncHandler(async (req, res) => {

    const id = req.user.userId;

    const client = await Client.findOneAndUpdate(
        {
            userId: id
        },
        {
            bio: req.body.bio
        },
        {
            new: true
        }
    );

    if (!client) {
        return res.status(404).json({
            message: 'Client not found'
        });
    }

    return res.status(200).json({
        message: 'Profile updated successfully',
        clientProfile: formatClient(client)
    });
});

module.exports = {
    getMyProfile,
    updateProfile
};

controllers/auth.controller.js

const User = require('../models/User');
const Client = require('../models/Client');

const {
    generateToken
} = require('../utils/jwt');

const createTestUser = async (req, res) => {

    const user = await User.create({
        name: 'Jyoti',
        email: 'jyoti@test.com',
        phone: '9999999999',
        role: 'client',
        isEmailVerified: true,
        isPhoneVerified: true,
        isActive: true
    });

    const client = await Client.create({
        userId: user._id,
        savedLawyers: [],
        blockedLawyers: [],
        bio: 'I am learning backend development.'
    });

    res.json({
        message: 'Test user created',
        userId: user._id,
        user,
        client
    });
};

const getToken = (req, res) => {

    const token = generateToken(
        req.params.userId
    );

    res.json({
        token
    });
};

module.exports = {
    createTestUser,
    getToken
};

routes/client.routes.js

const express = require('express');

const auth = require('../middleware/auth.middleware');

const {
    getMyProfile,
    updateProfile
} = require('../controllers/client.controller');

const router = express.Router();

router.get(
    '/profile',
    auth,
    getMyProfile
);

router.put(
    '/profile',
    auth,
    updateProfile
);

module.exports = router;

routes/auth.routes.js

const express = require('express');

const {
    createTestUser,
    getToken
} = require('../controllers/auth.controller');

const router = express.Router();

router.get(
    '/create-test-user',
    createTestUser
);

router.get(
    '/generate-token/:userId',
    getToken
);

module.exports = router;

Final structure

server/
│
├── server.js
├── package.json
├── .env
│
├── config/
│   └── db.js
│
├── models/
│   ├── User.js
│   └── Client.js
│
├── controllers/
│   ├── auth.controller.js
│   └── client.controller.js
│
├── routes/
│   ├── auth.routes.js
│   └── client.routes.js
│
├── middleware/
│   ├── auth.middleware.js
│   └── error.middleware.js
│
└── utils/
    ├── jwt.js
    ├── formatters.js
    └── asyncHandler.js

The basic role of each file was already explained. The important next step is understanding how the files communicate and why large projects separate responsibilities.

1. How files communicate

Node files communicate mainly through:

module.exports

and:

require()

For example:

// utils/jwt.js
module.exports = {
    generateToken
};

Another file can use it:

const { generateToken } = require('../utils/jwt');

Think:

jwt.js
   │
   │ exports
   ▼
generateToken
   │
   │ require
   ▼
auth.controller.js

./ vs ../

require('./file')

→ current folder

require('../file')

→ go one folder up first

2. express.Router()

Putting every route inside server.js becomes messy:

app.get(...)
app.post(...)
app.put(...)
app.delete(...)

So we create separate routers:

const router = express.Router();

For example:

routes/
├── auth.routes.js
├── client.routes.js
├── lawyer.routes.js
└── admin.routes.js

Each router manages one group of endpoints.

3. How route paths combine

In server.js:

app.use('/api/client', clientRoutes);

In client.routes.js:

router.get('/profile', auth, getMyProfile);

Express combines them:

/api/client
      +
/profile
      =
/api/client/profile

So the actual request is:

GET /api/client/profile

This lets server.js handle the main prefixes, while route files handle the individual endpoints.

4. Why controllers are passed without ()

Route:

router.get('/profile', auth, getMyProfile);

We pass:

getMyProfile

not:

getMyProfile()

Because:

getMyProfile

means:

"Here is the function. Run it when the request arrives."

Whereas:

getMyProfile()

means:

"Run it right now."

5. Middleware and controllers form a pipeline

For:

GET /api/client/profile

the flow is:

Request
   ↓
server.js
   ↓
client router
   ↓
auth middleware
   ↓
next()
   ↓
getMyProfile controller
   ↓
User/Client model
   ↓
MongoDB
   ↓
res.json()
   ↓
Response

The files are separate, but the request is still one continuous pipeline.

6. asyncHandler

Without asyncHandler, every async controller may need:

try {
    ...
}
catch(error) {
    next(error);
}

That becomes repetitive across hundreds of controllers.

So we can create:

const asyncHandler = (fn) => {
    return (req, res, next) => {
        Promise
            .resolve(fn(req, res, next))
            .catch(next);
    };
};

Then:

const getMyProfile = asyncHandler(async (req, res) => {
    const user = await User.findOne(...);
});

Conceptually:

Controller
    ↓
asyncHandler
    ↓
success → continue
error   → next(error)

7. Error middleware

Normal middleware:

(req, res, next)

Error middleware:

(error, req, res, next)

Example:

const errorHandler = (error, req, res, next) => {
    res.status(500).json({
        message: 'Server error'
    });
};

Then:

app.use(errorHandler);

So an error can travel:

Controller
   ↓
asyncHandler
   ↓
next(error)
   ↓
errorHandler
   ↓
500 response

8. Route vs Controller

This distinction is extremely important.

Route asks:

Which request should trigger something?

router.get('/profile', auth, getMyProfile);

Controller asks:

What should happen?

const getMyProfile = asyncHandler(async (req, res) => {
    // actual request logic
});

Think:

ROUTE       → WHERE?
CONTROLLER  → WHAT?

9. Why do we need services?

A controller can become huge if it contains:

database logic
business rules
calculations
permissions
notifications
formatting
...

So complicated reusable business logic can move into a service.

Route
  ↓
Controller
  ↓
Service
  ↓
Model
  ↓
Database

Example:

// client.service.js

const getClientProfile = async (userId) => {
    const user = await User.findOne({ _id: userId });
    const client = await Client.findOne({ userId });

    return { user, client };
};

Then the controller stays simple:

const getMyProfile = asyncHandler(async (req, res) => {
    const data = await getClientProfile(req.user.userId);

    res.json(data);
});

The service is especially useful when the same logic is needed by multiple controllers.

10. .env

Instead of hardcoding:

'mongodb://...'
'mysecretkey'

we can store configuration in:

.env

Example:

PORT=5000
MONGO_URI=...
JWT_SECRET=...

Then:

process.env.MONGO_URI
process.env.JWT_SECRET

This allows the same code to work with different environments such as:

development
testing
production

without changing the JavaScript code.

11. Model vs Database

This is another important distinction.

const User = require('../models/User');

User is a Mongoose model, not the database itself.

The flow is:

Controller
    ↓
User model
    ↓
Mongoose
    ↓
MongoDB

For example:

User.findOne(...)

means:

Ask the User model to perform a database operation.

12. Complete architecture

A large Express backend can therefore look like:

CLIENT
   ↓
SERVER
   ↓
ROUTES
   ↓
MIDDLEWARE
   ↓
CONTROLLER
   ↓
SERVICE
   ↓
MODEL
   ↓
MONGOOSE
   ↓
DATABASE

Errors have their own path:

Any layer
   ↓
next(error)
   ↓
Error middleware
   ↓
Response

13. The mental model to remember

Don't memorize the folder names.

Ask these questions:

Which URL?
     ↓
ROUTE

Does something need checking first?
     ↓
MIDDLEWARE

What should happen?
     ↓
CONTROLLER

Is there reusable/complex business logic?
     ↓
SERVICE

How do we access stored data?
     ↓
MODEL

Where is the data actually stored?
     ↓
DATABASE

The core idea

A large project doesn't separate files because the request itself is different.

It separates them because different responsibilities are easier to manage when they live in different places.

So instead of:

10,000 lines → one server.js

we get:

10,000 lines
      ↓
many small responsibilities
      ↓
many focused files
      ↓
one connected request pipeline

That is what makes a large backend manageable.

Part 1: Variables and Memory

How Python actually stores things

When you write x = 5, Python does two things: it creates an integer object 5 somewhere in memory, and it creates a name x that points at it. If you then write y = x, Python does not copy the number — it just makes y point at the same object x already points at.

a = [1, 2, 3]
b = a              # b now points at the SAME list object as a

print(id(a))       # some memory address, e.g. 140234099283776
print(id(b))       # the exact same address
print(a is b)      # True — they are literally the same object

Now watch what happens if you change the list through one name:

b.append(4)
print(a)            # [1, 2, 3, 4]
print(b)            # [1, 2, 3, 4]

Both changed, because there was only ever one list — a and b are just two labels on it.

Compare this to making an actual copy:

c = a.copy()         # creates a genuinely NEW list with the same contents
c.append(5)
print(a)              # [1, 2, 3, 4]     — unaffected
print(c)              # [1, 2, 3, 4, 5]
print(a is c)          # False — different objects now

== and is ask different questions:

• a == c → "do these look the same (same contents)?"

• a is c → "are these literally the same object in memory?"

Mutable vs Immutable — the most important distinction in the language

Immutable (cannot be changed after creation — any "change" makes a brand new object): int, float, str, bool, tuple

Mutable (can be changed in place, without creating a new object): list, dict, set, and custom class instances by default

Strings feel like they should be changeable, but they are not:

s = "hello"
s[0] = "H"          # TypeError: 'str' object does not support item assignment

Any string "modification" actually builds a new string and reassigns the name to it:

s = "hello"
s = s.upper()        # a NEW string "HELLO" is created; s now points to it
                       # the original "hello" string still exists in memory
                       # briefly, until nothing points to it and it's cleaned up

Why this matters for function arguments

def try_change_string(text):
    text = text.upper()     # this just repoints the LOCAL name "text"
    return text

original = "hello"
result = try_change_string(original)
print(original)    # "hello"  — the caller's variable never changed
print(result)       # "HELLO" — you have to explicitly return the new value

def try_change_list(items):
    items.append("new")     # this MUTATES the actual list object in place

original = ["a", "b"]
try_change_list(original)
print(original)    # ["a", "b", "new"]  — changed, with no return needed!

The rule: reassigning a parameter inside a function never affects the caller's variable. Mutating a mutable object that was passed in does affect the caller, because there's only one object and both the caller and the function are looking at it.

The classic trap this causes: mutable default arguments

def add_item(item, my_list=[]):    # DANGEROUS
    my_list.append(item)
    return my_list

print(add_item(1))    # [1]
print(add_item(2))    # [1, 2]   <-- surprising! you'd expect [2]

Why: the empty list [] in the function signature is created exactly once, at the moment the function is defined — not each time it's called. Every call that doesn't supply its own list reuses that same original list object, and it keeps growing across calls.

The fix — use None as a sentinel, and create a fresh list inside the function body each call:

def add_item(item, my_list=None):
    if my_list is None:
        my_list = []          # fresh list, created fresh on THIS call
    my_list.append(item)
    return my_list

Nested mutability — shallow vs deep copies

matrix = [[0, 0], [0, 0]]
shallow = matrix.copy()
shallow[0][0] = 99
print(matrix)     # [[99, 0], [0, 0]]  <- original changed too!

.copy() only copies the outer list. The inner lists are still the same shared objects. To fully separate everything, nested levels included:

import copy
deep = copy.deepcopy(matrix)
deep[0][0] = 55
print(matrix)      # unaffected this time

Dictionaries behave identically:

config = {"debug": True, "settings": {"retries": 3}}
shallow_copy = config.copy()

shallow_copy["debug"] = False
print(config["debug"])                      # True — outer level is independent

shallow_copy["settings"]["retries"] = 99
print(config["settings"]["retries"])        # 99 — inner dict is still SHARED

Part 2: Functions

Positional and keyword arguments

def describe(name, age, city="Unknown"):
    print(f"{name}, {age}, from {city}")

describe("Alice", 30)                       # positional
describe(name="Alice", age=30)              # keyword — order irrelevant
describe(age=30, name="Alice")              # same result as above
describe("Alice", city="NYC", age=30)       # mixed — positional args must come first

You can force some parameters to only be passable by keyword, using a bare *:

def create_user(name, *, email, is_admin=False):
    print(name, email, is_admin)

create_user("Bob", email="bob@example.com")   # fine
create_user("Bob", "bob@example.com")           # TypeError — email must be named

This prevents accidental mix-ups when a function has several parameters of the same type.

Variable-length arguments: *args and **kwargs

def show_args(*args, **kwargs):
    print("positional extras:", args)
    print("keyword extras:", kwargs)

show_args(1, 2, 3, name="Alice", age=30)
# positional extras: (1, 2, 3)                <- collected into a tuple
# keyword extras: {'name': 'Alice', 'age': 30}  <- collected into a dict

The reverse — unpacking a collection into separate arguments:

def add(a, b, c):
    return a + b + c

nums = [1, 2, 3]
print(add(*nums))              # * unpacks the list -> add(1, 2, 3)

kwargs = {"a": 1, "b": 2, "c": 3}
print(add(**kwargs))            # ** unpacks the dict -> add(a=1, b=2, c=3)

Scope — how Python decides which variable you mean

Python looks up names using the order: Local → Enclosing → Global → Built-in (often called the LEGB rule).

x = "global"

def outer():
    x = "outer"
    def inner():
        print(x)      # not found locally, found in enclosing scope -> "outer"
    inner()
    print(x)           # "outer"

outer()
print(x)                # "global" — never touched

A common trap — if you assign to a name anywhere inside a function, Python treats that name as local for the entire function body, even on lines before the assignment:

counter = 0

def broken_increment():
    counter = counter + 1
    # Python sees "counter = ..." in this function and decides
    # counter is LOCAL throughout the whole function.
    # So the "counter" being read on the right side is the
    # not-yet-assigned local one -> UnboundLocalError

Two ways to fix it:

def fixed_with_global():
    global counter
    counter = counter + 1     # explicitly refers to the global variable

def fixed_with_return():
    return counter + 1         # cleaner — no mutation of outer state at all

counter = fixed_with_return()   # caller decides what to do with the new value

In practice, prefer the return-based style. Reaching into outer scope with global makes code much harder to reason about as programs grow.

Closures — functions that remember their environment

def make_counter():
    count = 0
    def increment():
        nonlocal count       # like "global" but for the enclosing (not global) scope
        count += 1
        return count
    return increment

counter1 = make_counter()
counter2 = make_counter()

print(counter1())    # 1
print(counter1())    # 2
print(counter1())    # 3
print(counter2())    # 1  <- completely separate state from counter1

Each call to make_counter() creates a fresh count, and the returned increment function "closes over" (remembers) that specific count forever — even though make_counter() itself already finished running. This is how you get private, persistent state without writing a class.

Part 3: Classes

What self really is

class Dog:
    def __init__(self, name):
        self.name = name

    def bark(self):
        return f"{self.name} says woof"

rex = Dog("Rex")
print(rex.bark())         # normal syntax
print(Dog.bark(rex))      # produces the EXACT same result

rex.bark() is just convenient syntax for Dog.bark(rex) — Python automatically passes the object before the dot as the first argument. self is simply the name given to that first parameter; there's no hidden magic.

__init__ initializes, it doesn't construct

The object already exists by the time __init__ runs — __init__ just fills in its starting attribute values.

class Dog:
    species = "Canis familiaris"     # CLASS attribute — one copy, shared by all instances

    def __init__(self, name, age):
        self.name = name              # INSTANCE attribute — unique to each object
        self.age = age

Think of the class as a template stored once, and each instance as having its own private dictionary of overrides. Accessing rex.species checks rex's own storage first; not finding it there, Python falls back to the class. Accessing rex.name finds it directly on the instance.

rex = Dog("Rex", 3)
buddy = Dog("Buddy", 5)

Dog.species = "Canis lupus familiaris"    # change at the class level
print(rex.species)     # updated — both instances see the change, since neither has its own override

rex.species = "Special"                    # this creates an INSTANCE-level override on rex only
print(rex.species)      # "Special"
print(buddy.species)     # unaffected — still the class-level value

The same mutable-default trap, in class form

class ShoppingCart:
    items = []          # DANGER: this is a class attribute, shared by every instance

    def add(self, item):
        self.items.append(item)

cart1 = ShoppingCart()
cart2 = ShoppingCart()
cart1.add("apple")
print(cart2.items)      # ["apple"]  <- leaked in from cart1!

self.items.append(...) doesn't create a new instance attribute — it mutates the one shared list, because no instance-level items was ever separately created. Fix:

class ShoppingCart:
    def __init__(self):
        self.items = []        # a fresh, independent list per instance

    def add(self, item):
        self.items.append(item)

Dunder methods — how your objects plug into Python's built-in syntax

None of Python's operators are hardcoded to work on custom objects. +, ==, <, len(), printing, truthiness in if — all of these work because your class defines the matching "dunder" (double underscore) method.

class Money:
    def __init__(self, amount):
        self.amount = amount

    def __add__(self, other):        # enables: money1 + money2
        return Money(self.amount + other.amount)

    def __eq__(self, other):          # enables: money1 == money2
        return self.amount == other.amount

    def __lt__(self, other):          # enables: money1 < money2
        return self.amount < other.amount

    def __repr__(self):               # controls what print(money) shows
        return f"Money(${self.amount})"

    def __bool__(self):               # controls behavior in "if money:"
        return self.amount != 0

m1 = Money(10)
m2 = Money(20)
print(m1 + m2)            # Money($30)
print(m1 < m2)             # True
print(m1 == Money(10))     # True
if not Money(0):
    print("no money")       # this prints, since __bool__ returns False for Money(0)

Three decorators you'll see constantly

class Circle:
    def __init__(self, radius):
        self.radius = radius

    @property
    def area(self):                     # accessed like a plain attribute, no parentheses
        return 3.14159 * self.radius ** 2

    @classmethod
    def from_diameter(cls, diameter):   # alternate way to construct a Circle
        return cls(diameter / 2)

    @staticmethod
    def is_valid_radius(r):             # doesn't need self or cls — just grouped here logically
        return r > 0

c = Circle(5)
print(c.area)                       # 78.53975   -- notice: no parentheses used
c2 = Circle.from_diameter(10)
print(c2.radius)                     # 5.0
print(Circle.is_valid_radius(-1))    # False

• @property — call a method without (), as if it were a plain attribute (useful for computed values)

• @classmethod — receives the class itself (cls) instead of an instance; typically used for alternate constructors

• @staticmethod — receives neither self nor cls; it's a plain function grouped inside the class for organization

Inheritance and super()

class Puppy(Dog):
    def __init__(self, name):
        super().__init__(name, age=0)   # runs Dog's __init__ first
        self.is_puppy = True

super() gives you a handle to the parent class, letting you build on top of its behavior instead of rewriting it from scratch.

Part 4: Type Hints

Type hints look like they should enforce types, but by default, plain Python ignores them completely at runtime:

def add(a: int, b: int) -> int:
    return a + b

print(add("hello", "world"))    # runs fine, prints "helloworld" — no error!

So what are they for?

• Editor/IDE autocomplete and inline warnings

• Static analysis tools (like mypy) that check your code before running it

• Documentation that stays accurate, since it lives in the code itself

from typing import Optional, List, Dict, Union

def get_name() -> Optional[str]:     # means: returns a str, OR returns None
    return None

def get_scores() -> List[int]:        # a list of ints
    return [90, 85, 77]

def get_user() -> Dict[str, str]:     # a dict with string keys and string values
    return {"name": "Alice"}

def process(value: Union[int, str]) -> str:   # accepts either type
    return str(value)

# Python 3.10+ shorthand:
def get_name_new() -> str | None:
    return None

Some tools do enforce type hints at runtime — most notably Pydantic, which reads them and validates incoming data against them:

from pydantic import BaseModel
from typing import List, Optional

class Address(BaseModel):
    street: str
    city: str

class User(BaseModel):
    name: str
    age: int
    tags: List[str] = []
    address: Optional[Address] = None

Constructing a User(age="not a number") here would immediately raise a validation error — unlike plain Python functions, which silently let mismatched types through.

Part 5: async/await

The core idea: async is about not sitting idle while waiting, not about doing multiple things at the literal same instant. Only one line of Python code ever executes at a time — there's no multi-core magic here. The win comes purely from not blocking during waits (like network requests or database calls).

Synchronous version — everything waits in line

import time

def fetch_user():
    time.sleep(2)          # simulates a 2-second network call — freezes the whole program
    return "user data"

def fetch_orders():
    time.sleep(2)
    return "orders data"

start = time.time()
fetch_user()
fetch_orders()
print(f"Took {time.time() - start:.1f}s")    # Took 4.0s

Async version — waits overlap

import asyncio
import time

async def fetch_user():
    await asyncio.sleep(2)
    return "user data"

async def fetch_orders():
    await asyncio.sleep(2)
    return "orders data"

async def main():
    start = time.time()
    results = await asyncio.gather(fetch_user(), fetch_orders())
    print(f"Took {time.time() - start:.1f}s")    # Took 2.0s
    print(results)

asyncio.run(main())

Step by step:

1. fetch_user() runs until it hits await asyncio.sleep(2), then pauses, handing control back to the event loop (a scheduler managing all this).

2. The event loop, now free, starts fetch_orders(), which also pauses at its own await.

3. Both are now "parked" waiting on their timers simultaneously.

4. After 2 seconds (not 4), both resume, return their values, and gather collects them into a list.

The most common async bug: forgetting await

async def get_data():
    await asyncio.sleep(1)
    return {"status": "ok"}

async def main():
    result = get_data()          # forgot await!
    print(result)                  # <coroutine object get_data at 0x7f...>
    print(result["status"])        # TypeError — this isn't the actual data yet

    result = await get_data()     # correct — actually runs and waits for the result
    print(result["status"])         # "ok"

Calling an async def function without await doesn't run it — it just hands you back an unexecuted coroutine object.

async for and async with

async def list_users(db):
    async with db.client.start_session() as session:   # async context manager
        cursor = db.users.find({})
        async for user in cursor:                        # async iteration
            print(user)

Same shapes as regular with and for, but built for operations where each step might need to wait on I/O — such as fetching the next result from a database query over the network.

Part 6: Virtual Environments

By default, Python installs packages into one global location shared by everything on your machine. This becomes a problem the moment two different projects need different versions of the same library.

A virtual environment ("venv") is a self-contained, isolated copy of Python's package directory for a single project.

mkdir my_project && cd my_project

python -m venv venv
# Creates a venv/ folder: its own python, pip, and package storage

which python
# /usr/bin/python3        <- still the SYSTEM python, venv isn't active yet

source venv/bin/activate
# Shell prompt now shows (venv)

which python
# /Users/you/my_project/venv/bin/python     <- now rewired to the venv's copy

pip install fastapi uvicorn
# Installs ONLY inside venv/ — completely invisible to other projects

pip freeze > requirements.txt
# Records exact installed versions:
#   fastapi==0.115.0
#   uvicorn==0.30.1

deactivate
# Prompt returns to normal; "python" points back to the system version

On another machine (or a deployment server), nobody copies the venv/ folder itself — it gets rebuilt from the requirements file:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt    # reproduces the exact same set of packages

requirements.txt is the one artifact that travels with your project (usually committed to git); venv/ itself is added to .gitignore, since it's just a large, easily-regeneratable, machine-specific folder.

0. Why this file exists at all

Think about what a web server actually receives when a request comes in: a URL, some headers (little key-value pairs like Content-Type: application/json), and maybe a body. That's it. There is no little tag attached to the request that says "this is Priya, and she's logged in." The server has to be convinced.

Every other file in this app — the one that lets lawyers post replies, the one that lets clients book appointments — eventually writes a line like:

if (req.user.role === 'lawyer') { ... }

That line trusts req.user completely. It never asks "but how do we know this is really true?" This file, authController.js, is the only place in the entire app responsible for answering that question. Everywhere else just trusts the answer.

Why keep all of that logic in one file instead of spreading it around? Because if you ever need to change how identity is proven — swap JWTs for session cookies, add two-factor authentication, whatever — you want that to be a change to one file, not a hunt through fifty files that each independently decided to trust something. This idea has a name: separation of concerns. Each part of the app has exactly one job, and only one part of the app is allowed to decide "who is this person."

1. The imports

const bcrypt = require('bcryptjs');
const { createHash, randomUUID, timingSafeEqual } = require('crypto');
const jwt = require('jsonwebtoken');

Before touching what these do, slow down on the mechanics of require. In Node.js, require('some-package') runs that package's code and hands you back whatever it exported — usually one big object bundling together everything that package offers.

Line 1. require('bcryptjs') returns an object. That whole object gets stored in a variable named bcrypt. Later in the file you'll see bcrypt.hash(...) and bcrypt.compare(...) — those are just methods living on that object, accessed the normal way, with a dot.

Line 2 is the one worth actually stopping on. require('crypto') is Node's built-in cryptography toolbox, and it returns a genuinely huge object — dozens of functions for hashing, encryption, random number generation, and more. If you wrote:

const crypto = require('crypto');

...you'd get the whole toolbox under the name crypto, and you'd write crypto.createHash(...) every time you needed it. Instead, the file does this:

const { createHash, randomUUID, timingSafeEqual } = require('crypto');

The curly braces are object destructuring. Read it as: "Node, give me the whole crypto object, but then immediately reach inside it, pull out just these three named things, and give each one its own standalone variable name, matching what it's called inside the object." It is exactly equivalent to writing all of this:

const crypto = require('crypto');
const createHash = crypto.createHash;
const randomUUID = crypto.randomUUID;
const timingSafeEqual = crypto.timingSafeEqual;

Four lines of manual unpacking, collapsed into one line of shorthand. The practical payoff: from this point in the file onward, you write createHash(...) directly — no crypto. prefix needed, because createHash is now its own independent variable holding that one function.

Line 3. Same simple case as line 1 — require('jsonwebtoken') returns one object, stored as jwt, giving you jwt.sign(...) (build a token) and jwt.verify(...) (check a token) later in the file.

Why exactly these three from crypto, and nothing else? Every single import in this file maps to one specific job later on, with zero waste:

Nothing here is unused. That's a small but real signal, when you're reading someone else's code, that the file was written deliberately rather than copy-pasted from a dozen tutorials.

(This block only sets up tools — it has no inputs or outputs of its own to demonstrate. The functions below are what actually use these tools.)

2. The constants

const ACCESS_TOKEN_TTL = '15m';
const REFRESH_TOKEN_TTL = '30d';
const MAX_REFRESH_SESSIONS = 10;

First, the plain English: these three lines just create three named values sitting at the top of the file, available to every function below them. '15m' means "15 minutes," '30d' means "30 days," and 10 is just the number ten.

Why bother naming them, instead of just typing '15m' directly inside the function that needs it, three sections down? Imagine you didn't name it — you typed '15m' directly inline. Six months later, your team decides access tokens should last 30 minutes instead of 15. You'd now have to go find every single place in the codebase that happens to type the literal string '15m', and hope you found all of them, and hope none of them meant something unrelated that just happened to also be '15m'. This gets error-prone fast. By instead writing ACCESS_TOKEN_TTL once at the top and referencing that name everywhere else, changing the policy becomes a single-line edit, and every place that uses it picks up the new value automatically, guaranteed. This principle — say a value once, refer to it by name everywhere else — is called DRY: Don't Repeat Yourself. Here it's being applied not to logic but to a policy decision (how long should things last), which is just as important to keep in one place.

What actually is '15m', mechanically? It isn't a number of seconds you calculate yourself. It's a small duration string that gets handed to the jsonwebtoken library later (in signAccessToken, section 3), and that library has its own tiny internal parser that understands strings like '15m', '2h', '30d', '7 days', and converts them into a plain count of seconds behind the scenes. You will never see that conversion happen directly in this file — it's hidden inside jwt.sign — but it's worth knowing it's happening, because the next thing it does with that number is the actual mechanism behind "token expiry," which is just:

take the current time, add the duration, store that future moment as a plain number (seconds since January 1st, 1970 — this is called a "Unix timestamp"), and stamp it into the token as a field named exp.

Later, checking whether a token has expired is nothing magical — it's just: "is exp (a number) less than Date.now() (another number)?" You'll meet that check being performed automatically inside jwt.verify() in section 10.

Why is MAX_REFRESH_SESSIONS set to exactly 10, and why does that connect to MongoDB specifically? Here's a fact about MongoDB that has nothing to do with this app specifically: every single document stored in MongoDB — no matter what's in it — has a hard ceiling of 16 megabytes. You will basically never hit that limit with normal fields like a name or an email address. But this app's design stores a list called refreshTokens directly inside each user's document — one entry every time that person logs in, from any device. If nothing ever removed old entries, a user who logged in daily for ten years, across multiple browsers and phones, would have a document that just kept growing, forever, with no upper bound. 10 is this file's answer to the question "how many devices does one real person plausibly use at once?" — a login limit that also, as a side effect, guarantees this array can never come close to threatening that 16MB ceiling. The section-by-section mechanism that actually enforces this number lives in addRefreshSession (section 7) — this constant is just the policy; that function is the enforcement.

(Again, no direct input/output here — these are just labelled values other functions will use.)

3. signAccessToken — turning a user into a short-lived proof of identity

function signAccessToken(user) {
  return jwt.sign(
    { userId: user._id, role: user.role },
    process.env.JWT_ACCESS_SECRET,
    { expiresIn: ACCESS_TOKEN_TTL }
  );
}

What is this function's job, in one sentence? Given a user object (something already fetched from the database), produce a short string — the "access token" — that this user's browser can hand back on every future request as proof of "I already logged in, here's my receipt."

Reading jwt.sign's three arguments slowly:

1. The payload — { userId: user._id, role: user.role }. This is the actual data you want carried inside the token. Just two fields: which user this is, and what role they have ('client' or 'lawyer').

2. The secret — process.env.JWT_ACCESS_SECRET. This is a string pulled from an environment variable, not typed directly into the code. Why does that distinction matter? If the secret were typed directly as a string in this file, it would get committed to source control (git) the moment someone ran git push — visible to anyone with repo access, forever, in the history, even if you later remove it. Environment variables live only on the actual running server, configured separately for development, staging, and production, and are never written into any file that gets committed. This secret is the single most important piece of information in this entire authentication system — anyone who obtains it can forge tokens for any user, including an admin.

3. Options — { expiresIn: ACCESS_TOKEN_TTL }. This is where '15m' from section 2 finally gets used, and where it becomes that exp timestamp described a moment ago.

What comes back out is a JWT: a string made of three parts separated by dots, each part encoded in a text-safe format called base64url — a header, the payload, and a signature.

The single most important security idea in this whole function, and the one that trips up nearly everyone reading JWT code for the first time: the payload is signed, not encrypted. Signing and encrypting sound similar but do opposite things. Encrypting hides content so only someone with the right key can read it. Signing does not hide anything — it just attaches a tamper-proof seal. Anyone at all — a browser extension sitting on the user's machine, a proxy server somewhere on the network, literally anyone who gets a copy of this string — can decode the middle chunk with nothing more than a plain base64 decoder (no secret required) and read the payload in plain text: {"userId": "64f...", "role": "client", "exp": 1735689600}. The secret's only job is making the third chunk — the signature — impossible to forge. If an attacker tried editing the decoded payload to say "role": "admin" and then re-encoded it, the signature would no longer match what jwt.verify recomputes on the way back in (section 10), and the tampered token would be rejected outright. The practical rule this teaches you: never put a password, a credit card number, or anything genuinely secret inside a JWT payload. Think of it as a sealed glass envelope — sealed against tampering, but transparent to anyone who wants to look.

Why include role in this particular token, given that principle? This is a deliberate trade-off, not an oversight. Because role sits right there in the token, some other file's middleware — say, a check like requireRole('lawyer') guarding a lawyer-only page — can make its decision just by reading the token, without needing to ask the database "what is this person's role?" on every single request. That's a real performance win. The cost: if an admin changes someone's role while they're still logged in, their existing token keeps claiming the old role until it naturally expires — which, thanks to ACCESS_TOKEN_TTL, is a maximum of 15 minutes later. That bounded delay is the price paid for not hitting the database on every request.

Worked example

Input (a user document already loaded from MongoDB):

const user = {
  _id: "64f1a2b3c4d5e6f7a8b9c0d1",
  role: "lawyer",
  name: "Amara Chen"
};

signAccessToken(user);

Output (a single string — line breaks added here only for readability; the real thing is one continuous line):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJ1c2VySWQiOiI2NGYxYTJiM2M0ZDVlNmY3YThiOWMwZDEiLCJyb2xlIjoibGF3eWVyIiwiaWF0IjoxNzM2MjAwMDAwLCJleHAiOjE3MzYyMDA5MDB9.
Xk3pQz7...(signature bytes)...

If you took the middle chunk and ran it through any online base64 decoder, you would see, in plain readable text — no secret needed:

{ "userId": "64f1a2b3c4d5e6f7a8b9c0d1", "role": "lawyer", "iat": 1736200000, "exp": 1736200900 }

exp here is 1736200900 — 900 seconds (15 minutes) after iat (the "issued at" timestamp), which is exactly what ACCESS_TOKEN_TTL = '15m' produced.

4. signRefreshToken — a longer-lived, lower-power proof

function signRefreshToken(user) {
  return jwt.sign(
    { userId: user._id },
    process.env.JWT_REFRESH_SECRET,
    { expiresIn: REFRESH_TOKEN_TTL, jwtid: randomUUID() }
  );
}

This function looks almost identical to the last one — same three arguments to jwt.sign — which is exactly why it's worth reading it against signAccessToken, difference by difference, because every single difference here was a deliberate decision.

Difference 1 — the payload only has userId, no role. Think about what a refresh token is for: its one and only job, later, is to be traded in for a brand-new access token (you'll see this in section 10). It should never, by itself, be usable to make an authorization decision like "is this person allowed to see this lawyer-only page?" Giving it the absolute minimum information it needs to do its one job, and nothing more, is called the principle of least privilege — a token that leaks should leak as little useful information as possible.

Difference 2 — a completely different secret, JWT_REFRESH_SECRET, not JWT_ACCESS_SECRET. Why maintain two separate secrets instead of reusing one everywhere? Picture the worst case: somehow, one of these two secrets leaks (a misconfigured server, a leaked .env file, whatever). If both token types used the same secret, an attacker who obtained it could now forge both access tokens and refresh tokens for any user. With two separate secrets, a leak of one only compromises that one token type — the blast radius is cut in half. This is called token type separation.

Difference 3 — the expiry is '30d', not '15m'. This is the whole reason refresh tokens exist at all: nobody wants to type their password again every 15 minutes. The access token is short-lived on purpose (so a stolen one goes stale fast); the refresh token is long-lived on purpose (so a real user stays logged in for weeks without re-entering credentials), and it's used sparingly — only to mint new access tokens, not on every single request.

Difference 4 — a brand new option that didn't exist before: jwtid: randomUUID(). This one deserves the slowest read of the whole function.

jwtid sets a field inside the token called jti (JWT ID) — a random, unique identifier baked into this one specific act of signing a token. randomUUID() comes from Node's built-in crypto module and produces a string that looks like f47ac10b-58cc-4372-a567-0e02b2c3d479 — a cryptographically random value, meaning it isn't just "unlikely to repeat," it's astronomically unlikely to ever repeat, by design.

Why is this necessary at all? Picture a genuinely realistic scenario: one user logs into the app from their laptop and their phone within the same second — not an attack, just an ordinary person doing an ordinary thing. Both logins call signRefreshToken(user) with the same user object, meaning the exact same payload ({ userId: ... }), the exact same secret, and possibly the exact same second for iat/exp. Without anything else varying between them, it becomes at least theoretically possible for two signed token strings to end up identical or predictably related to one another. That would quietly break an assumption the rest of this file leans on hard, starting two functions from now: that each stored hashed token uniquely identifies exactly one session. Adding randomUUID() into the mix guarantees every single call to signRefreshToken, no matter the user, no matter the timing, produces a token that has never existed before, anywhere, and never will again.

Worked example

Input:

const user = { _id: "64f1a2b3c4d5e6f7a8b9c0d1" };

signRefreshToken(user);

Output (a JWT string, structurally like before but different payload/secret):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJ1c2VySWQiOiI2NGYxYTJiM2M0ZDVlNmY3YThiOWMwZDEiLCJqdGkiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJpYXQiOjE3MzYyMDAwMDAsImV4cCI6MTczODc5MjAwMH0.
9zLm2q...(different signature bytes)...

Decoding the middle chunk shows:

{
  "userId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "jti": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "iat": 1736200000,
  "exp": 1738792000
}

Notice: no role field at all (Difference 1), and exp is roughly 30 days after iat, not 15 minutes (Difference 3). Call this function again for the same user a second later, and jti will be a completely different random string, even though userId is identical — that's randomUUID() doing its job.

5. digestRefreshToken — turning a long token into a fixed, lookup-friendly fingerprint

function digestRefreshToken(refreshToken) {
  return createHash('sha256').update(refreshToken, 'utf8').digest('hex');
}

Before anything else: why hash the refresh token at all instead of just storing the raw token string in the database? Think about what the database contains if you store the raw token: if that database were ever stolen or leaked (a genuine, common category of real-world breach), the attacker would have every user's live refresh token in hand, ready to use immediately, with zero extra work. Storing a hash of the token instead means the database leak alone isn't enough — you'd need to reverse a one-way hash, which is (by design) computationally infeasible.

Reading the three chained method calls one at a time:

1. createHash('sha256') — asks Node's crypto module for a fresh, empty "hash object," specifically configured to use the SHA-256 algorithm. Nothing has been hashed yet at this point; this just prepares the tool.

2. .update(refreshToken, 'utf8') — feeds the actual token string into that hash object, telling it to interpret the string as UTF-8 encoded bytes (the standard way JavaScript strings are turned into raw bytes).

3. .digest('hex') — tells the hash object "you're done receiving input, now give me the final result," and asks for that result formatted as a hexadecimal string (characters 0-9 and a-f). SHA-256 always produces exactly 256 bits of output, and 256 bits written in hex is always exactly 64 characters — that specific number, 64, becomes important again in the very next function.

The core property to understand: this hash is deterministic. Feed the exact same string in a thousand times, get the exact same 64-character output a thousand times, no exceptions, no randomness involved anywhere.

Now contrast that directly with bcrypt.hash, which you'll meet properly in register (section 8), because the contrast is the entire point of this section. bcrypt.hash is deliberately non-deterministic — it generates a random "salt" internally every single time it's called, so hashing the identical password twice produces two different-looking results both times.

Why does a password need randomness while a refresh token specifically must not have it? It comes down to what each hash needs to be used for, later:

• A password hash needs to resist an attacker who has stolen the entire database and now has unlimited offline time to try to crack it, possibly using rainbow tables — huge, precomputed lookup tables mapping common passwords to their hashes. If every user's password were hashed the same deterministic way, two users who happened to share the password "password123" would have the identical stored hash — and cracking one instantly reveals the other. Randomizing per-user defeats that.

• A refresh token, by contrast, needs fast, exact lookup: "does any currently active session for this user match the token that was just presented?" To answer that efficiently, the stored value needs to be reproducible — hash the incoming token the same way every time, then simply compare it against what's stored. If refresh tokens used bcrypt instead, checking one incoming token against, say, ten stored sessions would require calling the (deliberately slow) bcrypt.compare() up to ten separate times, on every single refresh request from every user. The file's own design notes cite this specific performance problem as the actual reason an earlier version of this code, which did use bcrypt here, was abandoned.

There's also a sharper, genuinely-a-correctness-bug reason bcrypt would be actively wrong here, not merely slower: bcrypt silently truncates any input longer than 72 bytes — anything past that length is simply ignored during hashing. A JWT can easily exceed 72 bytes. That means two genuinely different long refresh tokens that happen to share the same first 72 bytes could be hashed by bcrypt into matching results — a false positive that would let the wrong token pass as valid. SHA-256 has no truncation limit like this at all; it processes an input of any length in full, so this entire failure mode simply cannot happen with it.

Worked example

Input:

digestRefreshToken("eyJhbGciOiJIUzI1NiIs...signRefreshToken output from above...");

Output (always exactly 64 hex characters, always the same for this exact input string):

7a3f9b2e1c6d4a8f0b5e2d9c1a7f4e6b8d3c0a9f2e5b7d1c4a6f8e0b3d5c7a91

Run it again on the exact same input string, get the exact same 64 characters back. Change even one character of the input — say, one letter in the token — and the output changes completely and unpredictably (this is called the avalanche effect), for example something like:

f1e4c7a0b3d6f9e2c5a8b1d4f7e0c3a6b9d2f5e8c1a4b7d0f3e6c9a2b5d8f1e4

6. refreshTokenMatchesDigest — safely checking "does this token match what's stored?"

function refreshTokenMatchesDigest(refreshToken, storedDigest) {
  if (typeof storedDigest !== 'string' || !/^[a-f0-9]{64}$/i.test(storedDigest)) {
    return false;
  }
  const presented = Buffer.from(digestRefreshToken(refreshToken), 'hex');
  const stored = Buffer.from(storedDigest, 'hex');
  return timingSafeEqual(presented, stored);
}

The guard clause on the first line, read slowly. /^[a-f0-9]{64}$/i is a regular expression — a pattern used to test whether a string has a certain shape. Breaking the pattern down symbol by symbol:

• ^ means "the match must start at the very beginning of the string" — no extra characters allowed before it.

• [a-f0-9] means "any single character that is a lowercase letter from a to f, or a digit from 0 to 9" — exactly the character set a hex digest is made of.

• {64} means "exactly 64 of the previous thing in a row" — not 63, not 65.

• $ means "and that must be the very end of the string" — no extra characters allowed after it either.

• The trailing i flag makes letter matching case-insensitive, so uppercase A-F would also pass.

Put together: "this string must be exactly 64 characters long, and every single one of them must be a hex digit — nothing more, nothing less." .test(storedDigest) runs storedDigest against that pattern and returns plain true or false.

Why does this check exist at all? Two overlapping reasons. First, it's a cheap sanity filter — from section 5, you already know a real SHA-256 hex digest is always exactly 64 characters, so anything that doesn't match this shape genuinely cannot be a valid digest, and there's no point doing any further, more expensive work on it. Second, and more concretely, it solves a real migration problem: imagine this app used to hash refresh tokens with bcrypt (as the earlier, abandoned version mentioned in section 5 did) — bcrypt hashes look like $2b$12$N9qo8uLOickgx2ZMRZoMy..., nowhere near 64 plain hex characters. Old session records left over from that earlier version, still sitting in the database, would fail this check immediately and safely return false — treated as simply invalid — instead of crashing the function, or worse, silently being fed into a comparison that assumes a shape they don't actually have.

Lines 3–4 convert text into raw bytes. Buffer.from(hexString, 'hex') takes a string like "7a3f9b2e..." and turns it into an actual sequence of raw binary bytes (a Buffer, Node's representation of raw binary data) — because the comparison on the next line needs to operate on real bytes, not on text characters.

Line 5 is the security-critical line in this whole function. timingSafeEqual(a, b) looks, at a glance, like it should do exactly what a === b does — check whether two things are equal. It does not work the same way underneath, and the difference matters enormously here.

Picture what a === b (or a hand-written loop comparing byte by byte) does internally: it compares the first byte; if that byte doesn't match, it stops immediately and returns false, without bothering to check any of the remaining bytes. That "stop as soon as you find a mismatch" behavior is normally a totally reasonable, harmless optimization. But it creates a subtle, measurable side effect: a guess that gets its first byte wrong returns false microscopically faster than a guess that gets the first ten bytes right and only fails on the eleventh — because more work had to happen before the second one could fail. To one single human eyeballing one single request, that time difference is completely invisible — we're talking fractions of a millisecond. But an attacker who can send millions of automated, precisely-timed requests, and carefully measure the response time of each one, can statistically detect that pattern and use it to reconstruct a correct secret one byte at a time, entirely without ever guessing the whole thing at once. This category of attack has a name: a timing attack.

timingSafeEqual is built specifically to defend against this: it always compares every single byte, every time, with no early exit, so the total time the comparison takes reveals absolutely nothing about how close a wrong guess was.

The general rule this function is teaching: any time your code compares a secret against a stored value — a token, a cryptographic signature, an API key — always use a timing-safe comparison, never === and never a hand-rolled loop. The one common, deliberate exception in this exact file is comparing passwords, and that's only safe because bcrypt.compare() (section 9) is already timing-safe internally, by construction — you don't need to wrap it in anything extra.

Worked example

Input (a genuine match):

refreshTokenMatchesDigest(
  "eyJhbGciOi...(the real refresh token)...",
  "7a3f9b2e1c6d4a8f0b5e2d9c1a7f4e6b8d3c0a9f2e5b7d1c4a6f8e0b3d5c7a91"
);

Output: true — because hashing that exact token with digestRefreshToken reproduces that exact 64-character string.

Input (a stale, no-longer-matching digest — imagine the session was rotated already, so the stored digest changed to something new):

refreshTokenMatchesDigest(
  "eyJhbGciOi...(the same old refresh token)...",
  "f1e4c7a0b3d6f9e2c5a8b1d4f7e0c3a6b9d2f5e8c1a4b7d0f3e6c9a2b5d8f1e4"
);

Output: false — the hash of the presented token doesn't equal the stored digest.

Input (a leftover bcrypt-format record from before the migration):

refreshTokenMatchesDigest(
  "eyJhbGciOi...(some token)...",
  "$2b$12$N9qo8uLOickgx2ZMRZoMy.eIkP1z4Y1a2b3c4d5e6f7g8h9i0j1"
);

Output: false, and immediately — this fails the regex shape check on line one and never even reaches timingSafeEqual.

7. addRefreshSession — recording a new logged-in device, safely

async function addRefreshSession(user, refreshToken, device) {
  const tokenHash = digestRefreshToken(refreshToken);
  const result = await User.updateOne(
    { _id: user._id, isActive: true },
    {
      $set: { lastLogin: new Date() },
      $push: {
        refreshTokens: {
          $each: [{ tokenHash, device: device || 'unknown', createdAt: new Date() }],
          $slice: -MAX_REFRESH_SESSIONS,
        },
      },
    }
  );
  if (result.modifiedCount !== 1) throw new Error('Could not persist refresh session.');
}

Big picture first: this function's job is to take a brand-new refresh token that was just issued, and record its hash (never the raw token itself — you already know why from section 5) into that user's document in the database, as one entry in their refreshTokens list, while also updating their "last logged in" timestamp.

The filter, { _id: user._id, isActive: true } — this is the single most important line in the whole file to understand deeply, because the pattern it demonstrates should become a reflex you reuse constantly.

Here's the naive, tempting-but-wrong alternative you might write instead: somewhere earlier in the code, you already fetched this user from the database and confirmed, in a plain JavaScript if statement, that user.isActive === true. Then, later, you run this update using only { _id: user._id } as the filter — no isActive check inside the update itself, because "I already checked that a moment ago."

The problem is the phrase "a moment ago." Between the instant you checked isActive in memory and the instant this update actually runs against the database, real time passes — however small. In that gap, it is entirely possible for a different, concurrent request to run — for example, an admin, in a completely separate request happening at the same time, deactivating this exact account. If that happens in the gap, your update would still go through, because your code never re-checks anything — it just trusts the answer it got a moment earlier. The result: you'd have silently created a brand-new, fully valid login session for an account that is, at this very instant, supposed to be deactivated. This category of bug has a name: a check-then-act race condition, or sometimes TOCTOU (time-of-check to time-of-use).

The fix, which is exactly what this line does, is to fold isActive: true directly into the same filter as the write itself. MongoDB re-evaluates that entire filter — including isActive: true — at the exact instant it performs the update, not a moment earlier, not based on some stale value you checked previously. If the account was deactivated even one millisecond before this exact line executes, the filter simply matches zero documents, and no write happens at all. This is called an atomic filter-and-update — "check and act" collapsed into one indivisible database operation instead of two separate steps with a gap between them. The general lesson to carry forward: whenever a condition genuinely matters for whether a write should happen, put that condition inside the same atomic operation as the write — never check it separately, beforehand, in application code, and trust that nothing changed in between.

$set: { lastLogin: new Date() }. new Date() captures whatever the current moment is, according to the server's clock, at the exact instant this line executes. It's stored on the document as a real BSON date value (MongoDB's native date type), not as a plain text string — which matters, because a real date type can later be sorted, filtered, and compared using normal date operators ($gt, $lt, etc.), whereas a string like "2026-09-07" would need to be parsed back into a real date every time before any of that would work correctly. This line runs on every login, which means the app always has an accurate "last seen" timestamp for every user, at essentially zero extra cost.

$push combined with $each and $slice — this is the mechanism that actually enforces the MAX_REFRESH_SESSIONS policy from section 2. Read it from the inside out:

• On its own, $push appends exactly one new item to an array field.

• $each changes that to "append a list of items in one call" — here, the list happens to contain exactly one new session object, but the syntax requires $each regardless, because $slice (below) can only be used alongside it, even when pushing a single item.

• $slice: -MAX_REFRESH_SESSIONS — which is -10 — then trims the entire resulting array down to keep only the last 10 entries. Negative numbers in $slice specifically mean "count backward from the end of the array," so -10 means "keep the final 10 items, discard everything before them."

Put together: every new login appends a new session entry at the end, and the moment the array would exceed 10 entries, the oldest one (or ones) are silently and automatically dropped from the front. This is a classic computer-science pattern called a bounded queue — new items always enter one end, and once the structure is "full," adding a new item pushes the oldest one out. Concretely, this means an 11th device logging in doesn't make the array grow to 11 — it makes the array stay at 10, quietly evicting whatever session had been sitting there longest.

device: device || 'unknown'. The || operator here isn't being used for boolean logic ("is this true or that true") — it's being used for its short-circuit fallback behavior: if the left-hand side (device) is "falsy" — meaning undefined, null, '' (empty string), or a few other values JavaScript treats as false-like — the whole expression evaluates to whatever's on the right-hand side instead, 'unknown'. Where does device come from? Looking ahead to register (section 8), it's read from req.headers['user-agent'] — and an HTTP client is technically allowed to send a request with no User-Agent header at all. Without this fallback, a client that omitted that header would cause device to end up undefined, and the database would end up storing the literal value undefined in that field — which is exactly the kind of inconsistent data this one small fallback exists to prevent.

The final line: if (result.modifiedCount !== 1) throw .... This is about correctly reading what updateOne actually tells you. It's tempting to assume "if the call didn't throw an exception, it must have worked" — but that's not what MongoDB's updateOne promises. Its return value is an object reporting, among other things, how many documents matched the filter (matchedCount) and how many were actually modified (modifiedCount) — and critically, if the filter matches zero documents (exactly the scenario from a few paragraphs ago, where isActive had already flipped to false), updateOne does not throw anything at all. It succeeds, at the plain JavaScript level, having matched and changed precisely nothing. This line is what turns "the database call technically didn't crash" into "the database call actually did what I needed it to do" — checking modifiedCount specifically, rather than just the absence of a thrown error, is the difference between assuming an outcome and verifying one.

Worked example

Input:

const user = { _id: "64f1a2b3c4d5e6f7a8b9c0d1", isActive: true };
const refreshToken = "eyJhbGciOi...(a freshly signed refresh token)...";
const device = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)";

await addRefreshSession(user, refreshToken, device);

What happens internally, step by step:

1. digestRefreshToken(refreshToken) produces something like "7a3f9b2e1c6d4a8f0b5e2d9c1a7f4e6b8d3c0a9f2e5b7d1c4a6f8e0b3d5c7a91".

2. MongoDB looks for a document where _id equals "64f1a2b3c4d5e6f7a8b9c0d1" and isActive is currently true.

3. Assuming it finds one, it sets lastLogin to the current timestamp, and pushes this new object onto refreshTokens:

   { tokenHash: "7a3f9b2e...c7a91", device: "Mozilla/5.0 (iPhone...)", createdAt: <now> }
   

4. If the array now has, say, 11 entries because this was an 11th device, $slice: -10 trims it back down to the 10 most recent, dropping the oldest one.

Output: the function returns undefined (it has no return value) on success — its real effect is the side effect on the database. If the account had been deactivated a moment before this ran, result.modifiedCount would be 0, and instead of quietly returning, the function would throw:

Error: Could not persist refresh session.

8. register — walked one line at a time, in the exact order it executes

const { name, email, phone, password, role } = req.body;

Same destructuring mechanic you saw explained slowly in section 1, now applied to req.body (whatever JSON the client sent) instead of to a package. Without destructuring, you'd write five separate lines: const name = req.body.name;, const email = req.body.email;, and so on. This one line does all five at once — and as a nice side effect, it also functions as instant, always-accurate documentation of exactly which fields this endpoint expects, right at the top of the function.

if (!name || !email || !phone || !password || !role) {
  return res.status(400).json({ message: "Missing required fields." });
}

This is fail-fast validation, and specifically, the ordering is deliberate: this check uses nothing but values already sitting in memory — no network call, no database query — so it's essentially free to run, and it runs before any of the more expensive steps below it (which do talk to the database). !name evaluates to true exactly when name is falsy (missing, empty string, etc.); chaining five of these with || means the whole condition becomes true the moment any single one of the five fields is missing. The HTTP status code 400 specifically means "the request itself is malformed" — there's no point asking the database anything yet, because the request wouldn't make sense even in a perfect world with a perfect database.

if (!["client", "lawyer"].includes(role)) {
  return res.status(400).json({ message: "Invalid role." });
}

["client", "lawyer"].includes(role) checks whether the string in role is one of exactly those two values, and nothing else — this is called a whitelist (an explicit list of what is allowed) as opposed to a blacklist (a list of what isn't). Why write this check at all, if the actual signup page's dropdown menu only ever shows those two choices to a real user clicking through the UI? Because the frontend is not a security boundary. Nothing about how the website's dropdown is built stops someone from bypassing the website entirely and sending a raw HTTP request directly to this endpoint — using a tool like curl or Postman — with the body {"role": "admin", ...}. The dropdown only constrains people using the actual web page; this one line of server-side code is what actually constrains everyone, regardless of how they're sending the request.

const existing = await User.findOne({ $or: [{ email }, { phone }] });
if (existing) {
  return res.status(409).json({ message: "Email or phone already registered." });
}

$or is a MongoDB query operator meaning exactly what it sounds like: "find one document where the email field matches this value, or the phone field matches this value." 409 Conflict is the HTTP status specifically meaning "this request conflicts with the current state of whatever it's trying to create."

Now, the honest concurrency reality of this check, which is important to understand rather than assume: this is a check-then-act race condition, structurally identical in shape to the one explained in section 7 — sometimes called TOCTOU (time-of-check to time-of-use). Picture two registration requests for the exact same email address arriving at nearly the same instant. Both findOne queries can run and come back completely empty — "no existing user found" — before either request has actually inserted anything into the database yet. Both requests, having each seen an empty result, now believe the email is free, and both proceed forward. This line, by itself, does not prevent two accounts from ending up with the same email. The actual backstop for that has to live one layer deeper, at the database schema level: a unique index on the email and phone fields. With that index in place, when the second (racing) request eventually reaches User.create() a moment later, MongoDB itself refuses the insert outright and throws a specific, recognizable duplicate-key error (error code 11000) — and that is the real guarantee against duplicates, not this findOne check. This findOne exists purely to produce a friendlier, more specific error message in the common, everyday, non-racing case — it is explicitly, by design, not the actual safety net.

const passwordHash = await bcrypt.hash(password, 12);

This is the promised contrast to digestRefreshToken from section 5 — the non-deterministic counterpart. bcrypt.hash(plaintext, saltRounds) takes two arguments: the plain password, and a "cost factor." 12 here means the underlying algorithm runs 2^12 (4,096) internal iterations. Deliberately raising this number makes the hashing operation slower — and that slowness is the entire point. It costs your server a negligible, barely-perceptible fraction of a second to hash one password during one real user's registration. But it costs an attacker who has stolen your entire database of hashes and is trying to guess passwords offline, billions of times over, an enormous, deliberately inflated amount of total compute time. 12 is a widely used, well-tested balance point between those two costs. Crucially, and unlike digestRefreshToken, bcrypt also automatically generates and embeds a random "salt" into its output on every single call — hash the identical password twice, and you'll get two different-looking hash strings both times. That single property is precisely why checking a password later, in login (section 9), can't just compare two hash strings with === — it has to use bcrypt.compare() instead, which specifically knows how to extract that embedded salt back out of the stored hash before recomputing anything.

const user = await User.create({ name, email, phone, passwordHash, role });

This uses shorthand property syntax — the writing-side mirror of the destructuring you saw on the reading side back at the top of this function. Because each variable name here (name, email, phone, passwordHash, role) already exactly matches the key name you want in the resulting object, JavaScript lets you skip repeating yourself: { name, email, phone, passwordHash, role } means precisely the same thing as writing out { name: name, email: email, phone: phone, passwordHash: passwordHash, role: role } in full. User.create() is a single Mongoose method that quietly does three separate things for you in one call: builds a complete document in memory, runs every validation rule defined on the schema (correct types, required fields present, any custom rules), and then actually saves it to MongoDB — from the point of view of the code calling it, this feels like one atomic step, even though multiple things are happening underneath.

if (role === "client") {
  await Client.create({ userId: user._id });
} else {
  await Lawyer.create({ userId: user._id, specialization: [], yearsOfExperience: 0, consultationFee: 0 });
}

This is a data-modeling decision worth understanding on its own terms, sometimes called profile fan-out. The User document itself only holds what's genuinely common to every account, regardless of role: identity and login credentials — name, email, phone, password hash, role. Anything that's specific to one particular role — a lawyer's list of legal specializations, their years of experience, their consultation fee — lives instead in a completely separate document, in a separate MongoDB collection (Lawyer or Client), linked back to the user only by storing that user's _id as a field named userId. This is exactly why, elsewhere in this app, "a lawyer" conceptually corresponds to two different IDs referring to the same real person: User._id (their login identity) and Lawyer._id (their profile document) — meaning some other piece of code that needs the lawyer's profile has to perform a second lookup, something like Lawyer.findOne({ userId: someUsersId }), to bridge from one to the other.

The concurrency bug this section explicitly flags lives right here. If User.create() on the previous line succeeded, but this call — whichever of Client.create() or Lawyer.create() applies — then throws for any reason at all (a validation failure, a dropped database connection, anything), there is now a User document sitting permanently in the database with no matching profile document at all. Nothing anywhere in this function reaches back and undoes the earlier User.create() — there is no automatic rollback. The correct, complete fix — which the file's own design notes explicitly mark as future work rather than something already solved — is a MongoDB transaction: a mechanism that lets multiple writes spanning multiple collections either all succeed together, or all roll back together, with no possibility of the database ever being caught in a visible half-finished state in between.

await addRefreshSession(user, refreshToken, req.headers['user-agent']);

This one line demonstrates a small but genuinely important JavaScript syntax rule: bracket notation, used here because the property name has a hyphen in it. Dot notation (req.headers.something) only works when the property name you're accessing is also a legal JavaScript variable name — and hyphens are not legal inside variable names, because a hyphen is the subtraction operator. If this code had been written as req.headers.user-agent, JavaScript would actually try to parse that as "take the value at req.headers.user, then subtract something named agent" — nonsense in this context, and it would either throw an error or silently produce something completely wrong. Bracket notation, req.headers['user-agent'], sidesteps the whole problem entirely by treating the whole thing as a plain string used as a key, rather than as literal JavaScript syntax to be parsed. Any HTTP header containing a hyphen — and there are many common ones, like content-type or x-forwarded-for — needs exactly this same bracket treatment. This is also a small but genuine networking detail worth knowing on its own: HTTP header names very commonly contain hyphens as a matter of convention, which is precisely why Express exposes all headers as a plain object you index into with brackets, rather than something you'd naturally dot into.

} catch (err) {
  return res.status(500).json({ message: "Registration failed.", error: err.message });
}

This is a manually written try/catch, rather than a cleaner, more reusable pattern you might see in a more mature codebase — something like a shared asyncHandler wrapper combined with a custom AppError class that centralizes how errors get turned into responses. There's a genuine security concern worth flagging in this specific line: error: err.message sends whatever the raw, internal error message says directly back to whoever made the request. In the ordinary case, this is completely harmless — usually it's something benign like "email already exists." But if the underlying error came from somewhere less expected — say, a raw database driver failure, or some unrelated internal exception — its message could end up describing internal implementation details (database names, internal file paths, library internals) that have no business being visible to an outside client at all. In a cleaner rewrite, this catch block should ideally shrink down to simply re-throwing the error and letting one single, centralized, shared error handler elsewhere in the app decide, in one place, what's actually safe to reveal externally.

Worked example

Input (an HTTP POST request body):

{
  "name": "Amara Chen",
  "email": "amara@example.com",
  "phone": "+15551234567",
  "password": "correcthorsebatterystaple",
  "role": "lawyer"
}

Output on success — a new User document is created (with a bcrypt password hash, never the plain password), a matching Lawyer document is created, a refresh session is recorded, and the HTTP response sent back to the client is something like:

{
  "accessToken": "eyJhbGciOi...(a signAccessToken output)...",
  "refreshToken": "eyJhbGciOi...(a signRefreshToken output)...",
  "user": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Amara Chen", "role": "lawyer" }
}

Output on a validation failure — same request, but "role": "admin" instead:

{ "message": "Invalid role." }

sent with HTTP status 400.

Output on a duplicate email — same request, but this email was already registered by someone else:

{ "message": "Email or phone already registered." }

sent with HTTP status 409.

9. login — checking a claim of identity against stored credentials

const user = await User.findOne({ email }).select('+passwordHash');

To understand .select('+passwordHash'), you first need to know something about how the User schema is defined elsewhere in the app: it marks the passwordHash field with select: false. That setting means, by default, every single query against the User model anywhere in this entire codebase — User.find(), User.findById(), all of them, automatically leaves passwordHash out of whatever it returns, with zero extra effort required from whoever happens to be writing that particular query. This is a strong, safe default: some completely unrelated controller elsewhere in the app, written by someone who has never thought about password security at all, can freely query users for, say, a public profile listing, and it is simply impossible for that query to accidentally leak a password hash into an API response — because the field was never even fetched from the database in the first place, let alone serialized into JSON.

.select('+passwordHash') is the deliberate, explicit override to that default. The + prefix specifically means "yes, I am aware this field is normally hidden, and I specifically want it included, right here, right now, because this particular piece of code genuinely needs it." The practical benefit: it forces every single place in the codebase that actually needs to compare passwords to say so explicitly, right at that exact call site — rather than password access being some ambient possibility lurking everywhere, invisible until something goes wrong.

if (!user || !user.isActive) {
  return res.status(401).json({ message: "Invalid credentials." });
}

This line is about preventing user enumeration. Notice: "no user with this email exists at all" and "a user with this email exists, but their account has been deactivated" produce the exact same outcome — same status code (401), same message ("Invalid credentials."). Consider what would happen if these two cases produced differently worded responses instead — say, "No account found" versus "Account disabled". An attacker could then send login attempts for a huge list of email addresses they're curious about, never even attempting a password, and use only the wording difference in the response to silently build up a list of which of those email addresses correspond to real, registered accounts on this system — a genuine privacy and security leak, achieved without ever guessing a single password. Making the two outcomes indistinguishable from the outside closes that door entirely.

const isMatch = await bcrypt.compare(password, user.passwordHash);
if (!isMatch) {
  return res.status(401).json({ message: "Invalid credentials." });
}

bcrypt.compare(plaintext, storedHash) is the counterpart to bcrypt.hash from section 8. Internally, it reads the salt that's embedded directly inside storedHash (recall: bcrypt bakes the salt right into its own output string), redoes the exact same hashing computation on the freshly submitted plaintext password using that same extracted salt, and then checks whether the two results match. This comparison is already timing-safe internally, by construction — which is exactly why this file doesn't need to wrap it in timingSafeEqual the way refreshTokenMatchesDigest had to in section 6; that protection is already built into bcrypt.compare itself.

Now look closely at the exact wording of this failure message compared to the one two lines above: identical, character for character — "Invalid credentials.", both times, with the same 401 status both times. This is the second half of the anti-enumeration design started above: whether the underlying reason is "no such email exists at all," or "the account exists but is deactivated," or "the password submitted is simply wrong," an attacker probing this endpoint receives back the exact same signal every single time, with absolutely no way to distinguish any of those three genuinely different situations from the outside.

Worked example

Input (correct credentials, active account):

{ "email": "amara@example.com", "password": "correcthorsebatterystaple" }

Output:

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "user": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Amara Chen", "role": "lawyer" }
}

Input (an email that was never registered):

{ "email": "nobody-registered-this@example.com", "password": "anything" }

Output (status 401):

{ "message": "Invalid credentials." }

Input (correct email, wrong password):

{ "email": "amara@example.com", "password": "wrongGuessHere" }

Output (status 401 — indistinguishable from the previous case):

{ "message": "Invalid credentials." }

Input (correct email and password, but the account was deactivated by an admin):

Output (status 401 — again, indistinguishable):

{ "message": "Invalid credentials." }

10. refreshToken — the most intricate handler in the file

let payload;
try {
  payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);
} catch {
  return res.status(401).json({ message: "Invalid or expired refresh token." });
}

jwt.verify(token, secret) performs two distinct checks in one call, and either one failing causes the whole call to throw an exception rather than return some kind of "false" value: first, is the signature actually valid — was this token really signed using JWT_REFRESH_SECRET, and has it not been tampered with since? Second — using the same exp/Date.now() mechanism first described back in section 2 — has the token's expiry timestamp already passed? If either check fails for any reason, jwt.verify throws, and that's exactly why this call needs its own dedicated try/catch, separate from any error handling elsewhere in the app.

catch { ... } — with nothing at all inside the parentheses — is called optional catch binding. The normal, more familiar form is catch (err) { ... }, which lets you inspect exactly what went wrong inside the err variable. Here, the code deliberately doesn't do that, because it genuinely does not care why verification failed — an expired token, a tampered token, a completely malformed garbage string — all of them are treated identically, as "reject this." Since the specific error is never going to be looked at, there's no reason to even bother naming a variable for it.

const user = await User.findById(payload.userId).select("+refreshTokens.tokenHash");

It's important to be precise about what passing jwt.verify actually proves, and what it does not prove. It proves the token's signature is legitimate, and that the token hasn't expired yet. It does not prove that the token hasn't been revoked — for example, that the user hasn't already logged out on that device (section 11), or that this exact token hasn't already been used once already as part of the rotation mechanism you're about to read below. That distinction is exactly why the very next step reaches into the database to fetch this user's actual, current, mutable list of active sessions to cross-check against: a cryptographic signature is a fixed mathematical fact about a string that, once true, stays true forever — it can never be "un-issued" after the fact purely by its own logic. Making revocation possible at all requires checking against something external and mutable that lives outside the token itself — which is precisely what this database lookup provides.

const oldTokenHash = digestRefreshToken(refreshToken);
const hasMatchingSession = user.refreshTokens.some((session) => (
  refreshTokenMatchesDigest(refreshToken, session.tokenHash)
));

.some() is a built-in array method that walks through user.refreshTokens one entry at a time and, for each session, runs the given function. The very first time that function returns true for any element, .some() stops immediately and returns true for the whole call, without bothering to check any of the remaining array elements — this is called short-circuit evaluation, the same underlying idea you already saw at work in the device || 'unknown' fallback back in section 7, just applied here to loop control instead of a single expression. Every individual comparison performed inside this loop goes through refreshTokenMatchesDigest from section 6 — which means every single comparison happening here, not just some overall final result, is timing-safe.

This whole check is the actual mechanism that makes revocation genuinely work, and it's worth restating plainly: a JWT's signature being valid is a permanent, unchangeable mathematical fact — a signed token has no built-in concept of "and by the way, I've since been logged out." The only way to make a previously-valid, unexpired token stop working is to check it against something outside the token entirely — here, the current, mutable list of session hashes stored on this specific user's document. If logout (section 11) has already removed this particular session's hash from that array, .some() finds no matching entry anywhere in the list, hasMatchingSession becomes false, and this otherwise perfectly valid, correctly-signed, not-yet-expired token gets rejected anyway. This is the entire reason this file goes to the trouble of storing hashed sessions server-side in the first place, rather than simply trusting JWTs as fully "stateless" tokens the way some simpler designs do.

const newTokenHash = digestRefreshToken(newRefreshToken);
const rotation = await User.updateOne(
  { _id: user._id, isActive: true, 'refreshTokens.tokenHash': oldTokenHash },
  { $set: { 'refreshTokens.$[session].tokenHash': newTokenHash } },
  { arrayFilters: [{ 'session.tokenHash': oldTokenHash }] }
);
if (rotation.modifiedCount !== 1) {
  return res.status(401).json({ message: 'Refresh token was already used or revoked.' });
}

This is the single most important concurrency mechanism in the entire file — worth reading slower than anything else here.

Look carefully at the filter object first: { _id: user._id, isActive: true, 'refreshTokens.tokenHash': oldTokenHash }. Focus on that third condition specifically: it says "only match this document if the old hash is still currently present somewhere in the array, right at this exact instant, at the moment this write is actually executing." This is the same core idea as addRefreshSession's filter back in section 7 — folding a condition directly into the atomic write itself, rather than checking it separately beforehand — but here it's being used to do something more powerful. This specific pattern has a name: optimistic concurrency control, sometimes also called compare-and-swap: "update this field, but only if it still currently has the exact value I expect it to have; if it doesn't, do nothing at all."

Here's the exact replay attack this single mechanism defends against. Imagine an attacker somehow steals a valid, not-yet-expired refresh token — say, through a compromised browser extension sitting on the victim's machine. At some point afterward, purely by unlucky timing, both the legitimate user (using their phone, say) and the attacker (using the stolen token) happen to send a refresh request using that exact same token, at nearly the same instant — a genuine, real race condition, not a hypothetical one. Both of these requests pass every single check described above: both signatures verify fine, neither token has expired, and both find a matching session in the array via .some(). But only one of them can possibly win at this specific line. Whichever updateOne call happens to physically reach MongoDB first finds oldTokenHash still present in the filter, and succeeds — rotation.modifiedCount becomes 1, and the stored hash gets replaced with newTokenHash. The instant that happens, the second racing request's filter — which is still looking for the old hash — no longer matches anything at all, because the underlying document has already changed out from under it, milliseconds earlier. Its modifiedCount comes back 0, and it gets correctly rejected with "already used or revoked." The atomicity of a single MongoDB write guarantees that only one of the two racing requests can ever win — there is no possible outcome where both succeed.

arrayFilters is the piece that makes the actual field update precise enough to work at all. refreshTokens is an array, and any given user could have up to 10 separate session subdocuments sitting inside it at once (thanks to MAX_REFRESH_SESSIONS from section 2). The path 'refreshTokens.$[session].tokenHash' uses a special positional placeholder, $[session], which reads as "whichever specific array element the arrayFilters option below identifies as the one named session." And arrayFilters: [{ 'session.tokenHash': oldTokenHash }] is exactly what defines that: "the one particular array element whose tokenHash field equals oldTokenHash." Without this mechanism, MongoDB would have no way at all to know which one of up to ten array entries you actually meant to update — you'd need some other, clunkier approach to target one specific element inside an array.

Worked example

Input (client sends its current refresh token, along with a freshly generated newRefreshToken the server has already produced internally for this request):

const refreshToken = "eyJhbGciOi...(the client's existing, currently-stored token)...";
// newRefreshToken was generated earlier in the handler via signRefreshToken(user)

Output on success — the old session's stored hash is atomically replaced with the new one, and the client receives:

{
  "accessToken": "eyJhbGciOi...(a brand-new signAccessToken output)...",
  "refreshToken": "eyJhbGciOi...(newRefreshToken)..."
}

Output if the exact same (now-stale) refresh token is presented a second time — for example, by a browser tab that cached the old token and tried to reuse it after rotation already happened — status 401:

{ "message": "Refresh token was already used or revoked." }

Output if the token has simply expired (30+ days old) — status 401:

{ "message": "Invalid or expired refresh token." }

11. logout — deliberately forgiving, on purpose

try {
  payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);
} catch {
  return res.status(200).json({ message: "Logged out successfully." });
}

This has the exact same shape as the try/catch in refreshToken above — same jwt.verify call, same empty catch — but notice the status code on failure is completely different: 200 here, versus 401 there. This difference is a deliberate design choice about user experience combined with security reasoning, not an inconsistency to fix. Think about what someone hitting the logout endpoint actually wants: exactly one outcome — to no longer be logged in. If it turns out their token was already garbage, already expired, or was never even valid in the first place, then the end state they were actually asking for — "I am now logged out" — is already true, trivially. Treating that situation as an error would be actively misleading to the caller; nothing needs fixing, nothing went wrong from their point of view, and there's no useful corrective action for them to take. This specific behavior — doing the same operation on an already-invalid or already-applied input and getting the same successful result every time, with no error — is called idempotent logout (more generally, an idempotent operation is one where doing it once, or doing it many times, produces the same end state).

await User.updateOne(
  { _id: payload.userId },
  { $pull: { refreshTokens: { tokenHash: digestRefreshToken(refreshToken) } } }
);

$pull is a MongoDB update operator that removes every array element matching a given condition — here, specifically the one subdocument (if any) whose tokenHash matches the digest of exactly this one token being logged out with. Because it's scoped to that one exact hash, and not to "clear the whole array," logging out on one device — a phone, say — leaves up to nine other possible active sessions (a laptop, a tablet, a different browser) completely untouched. This is exactly the behavior you'd want in a real multi-device app: logging out should end the session you're actually using right now, not silently sign the user out of every device they own everywhere else.

Worked example

Input (a currently valid, active refresh token):

{ "refreshToken": "eyJhbGciOi...(a live session's token)..." }

Output (status 200) — this session's entry is removed from refreshTokens, all other sessions untouched:

{ "message": "Logged out successfully." }

Input (a garbage string, or an already-expired token):

{ "refreshToken": "not-a-real-token-at-all" }

Output (still status 200, same message — no error surfaced to the caller):

{ "message": "Logged out successfully." }

12. The Postman test table (reference)

Look at the shape of this table before the specific rows, because the organizing idea is the actual lesson here, more than any one specific test case: the tests are grouped by category of scenario — (happy path), (validation), (auth failure), (not found/revoked), (edge case: role tampering), (edge case: duplicate), (rotation replay), (logout idempotency). A genuinely thorough test plan for any authentication system, not just this one, should aim to cover that same shape of ground: does the ideal, everything-goes-right path actually work; is obviously bad input rejected early, before it can cause any damage; are wrong credentials rejected without ever leaking information about why they were wrong; are already-used, already-expired, or already-revoked tokens correctly caught and rejected; can someone bypass an intended whitelist by simply sending an unexpected raw value straight to the API; can the same resource accidentally end up created twice; can a token meant to be used exactly once actually be used twice; and does "undo" behavior, like logging out, still behave sensibly even when handed already-broken input. Test #7, labeled "rotation replay," directly exercises the atomicity mechanism from section 10 — reusing a token from before a rotation happened should fail specifically because that token's hash no longer exists anywhere in the array, having already been overwritten by the rotation.

13. Reading the refreshToken flowchart as a decision tree

Every diamond-shaped decision point in that flowchart corresponds to one real, specific if statement or filter condition inside section 10's code — nothing in the diagram is decorative:

• "refreshToken present?" → the very first input-validation check, before anything else runs.

• "Does jwt.verify throw?" → the try/catch wrapped around the verification call.

• "Not found, or !isActive?" → the check immediately after User.findById.

• "No matching session found?" (via .some()) → the revocation check.

• "modifiedCount !== 1?" → the atomic, compare-and-swap rotation check.

The value of actually drawing a chart like this out before writing a handler (or while trying to make sense of one someone else already wrote) is that it forces every branch to become explicit, on paper, including the one branch that's genuinely easy to forget entirely: "what if the token is syntactically perfect, correctly signed, and not yet expired — but was already logged out?" That branch simply doesn't exist at all in a naive JWT implementation that trusts tokens as purely "stateless" proof — it exists here only because of the deliberate session-hash-checking design built out across every function in section 10.

Self-check before moving on

1. Why does signRefreshToken deliberately leave role out of its payload, while signAccessToken includes it? What's the worst-case consequence if that were reversed?

2. Why is digestRefreshToken deterministic while bcrypt.hash is deliberately not — and for each one, why does that specific property matter for the specific job it does?

3. Walk through, step by step, exactly why two simultaneous requests using the same stolen refresh token can never both succeed inside refreshToken.

4. Why does login return the literal same error message and status code for "no such user exists" and "the password was simply wrong"?

5. Why does addRefreshSession's database filter include isActive: true directly inside it, instead of checking isActive earlier in the code and simply trusting that earlier result?

6. Trace where in this file a plain string like '15m' actually gets turned into a real numeric timestamp — and then trace where, later, that same timestamp gets read and checked again.

This walks the file top to bottom, in the order the code actually runs. For every chunk of code, everything relevant : software design, security, JavaScript mechanics, Mongoose, MongoDB, algorithms, concurrency, networking, date/time : is explained together, right where it happens, instead of grouped into separate topic chapters. Small bracket tags like [Security] or [JS] are kept so you can still recognize what kind of concept you're looking at, but nothing is split into its own section anymore.

Block 0 — Imports and file-level setup

const Lawyer = require('../models/lawyer');
const Client = require('../models/client');
const Availability = require('../models/availibility');
const asyncHandler = require('../middleware/asyncHandler');
const AppError = require('../utils/AppError');
const { sendSuccess, paginationMeta } = require('../utils/apiResponse');

• [Networking/Node basics] require(...) is Node.js's module system — it pulls in code defined in another file. Each line gives this file a local variable (Lawyer, Client, etc.) pointing at whatever that other file exports.

• [JS] The last line is destructuring an object export: apiResponse.js exports an object with (at least) two functions on it, sendSuccess and paginationMeta, and this line pulls both out into standalone variables in one shot, instead of writing const sendSuccess = require('../utils/apiResponse').sendSuccess; twice.

• [SE — audience-based separation] The fact that this file is called *public*LawyerController, and only ever imports things needed to read and format lawyer data (never anything for a lawyer editing their own profile), is itself a design signal: this file only serves anonymous/public callers, never a lawyer viewing their own account. A sibling file (lawyerProfileController.js, not shown here) handles that other audience. Splitting by who's allowed to call this — not just what it technically does — means this whole file can safely assume "never trust the caller" with no exceptions.

Block 1 — LAWYER_FIELDS (the shared projection object)

const LAWYER_FIELDS = {
  specialization: 1,
  yearsOfExperience: 1,
  courtsPracticed: 1,
  languages: 1,
  consultationFee: 1,
  bio: 1,
  profilePhoto: 1,
  officeAddress: 1,
  rating: 1,
  reviewCount: 1,
  totalConsultations: 1,
};

• [MongoDB — projection] This is a MongoDB projection object. 1 means "include this field in the result." You could use 0 to mean "exclude," but you generally can't mix 1s and 0s in the same object (except _id). This object gets reused later inside $project stages (see Block 3.9 and Block 5) — written once here, spread wherever needed.

• [Security — data minimization] Look at what's missing: no verificationStatus, no isProfileVisible, nothing payment-related. Because this object later feeds MongoDB's own $project stage, those excluded fields are never even pulled out of the database for this request — not "fetched then hidden," but never fetched at all. That's a stronger guarantee than filtering in application code, and it's the core of least privilege: only touch the data you're actually willing to expose.

• [SE — DRY] Because this is a single named constant reused by three different handlers (getLawyers, getLawyerById, getLawyerRankings), the "list of public-safe fields" only has to be written and maintained in one place.

Block 2 — formatLawyer(raw)

function formatLawyer(raw) {
  return {
    _id: raw._id,
    user: { _id: raw.user._id, name: raw.user.name },
    specialization: raw.specialization,
    yearsOfExperience: raw.yearsOfExperience,
    courtsPracticed: raw.courtsPracticed,
    languages: raw.languages,
    consultationFee: raw.consultationFee,
    bio: raw.bio,
    profilePhoto: raw.profilePhoto,
    officeAddress: raw.officeAddress,
    rating: raw.rating,
    reviewCount: raw.reviewCount,
    totalConsultations: raw.totalConsultations,
  };
}

• [SE — shared reshape function] This function is called from getLawyers, getLawyerById, and getLawyerRankings (Block 3.12, Block 4, Block 5) — three handlers that fetch data in different ways (aggregation pipeline vs. .populate()), but all funnel their result through this one function before responding. That guarantees the frontend always sees the exact same "lawyer object" shape no matter which endpoint it called — one parser, not three slightly-different ones that drift apart over time.

• [JS — pure function] Given the same raw input, this always returns the same output, and it never touches anything outside itself (no DB calls, no global state). That predictability is exactly why it's safe to call from three unrelated places — nothing calling it can accidentally affect anything else calling it.

• [Security] Notice it explicitly hand-picks each field by name rather than doing something like return raw;. Even though LAWYER_FIELDS already limited what the database sends back, this function is a second, independent safety net at the application layer — an extra field accidentally left in raw still won't leak out through here.

• [JS — nested object literal] user: { _id: raw.user._id, name: raw.user.name } builds a brand-new nested object rather than just doing user: raw.user — again deliberately picking only two sub-fields instead of passing the whole raw.user object through.

Block 3 — exports.getLawyers

3.1 — The wrapper

exports.getLawyers = asyncHandler(async (req, res) => {
  // ...
});

• [SE — DRY error handling] In plain Express, if an async function throws, Express does not automatically catch it — you'd normally need try { ... } catch (err) { next(err); } in every handler. asyncHandler is a small reusable wrapper (defined in middleware/asyncHandler.js) that does this once, generically, for whatever function you hand it. Every throw new AppError(...) you'll see below automatically gets routed to Express's central error handler because of this wrapper — no repeated boilerplate needed in each handler.

• [JS] async (req, res) => {...} is an arrow function marked async, meaning you can await promises inside it (see 3.10) and it always returns a promise itself.

3.2 — Destructuring the query string

const {
  specialization, court, language, minFee, maxFee, minExperience, minRating, name,
  sortBy = 'rating', order = 'desc', page = 1, limit = 20,
} = req.query;

• [JS — destructuring with defaults] Pulls each named property off req.query into its own variable in one line. = 'rating', = 'desc', = 1, = 20 are default values — they only kick in if that specific key is undefined (i.e., the caller genuinely never sent it). A subtlety: the default only fires for undefined, not for an empty string — if sortBy were somehow '', the default would not apply.

• [Networking — query strings are text] req.query comes from the URL's query string (everything after ?). HTTP doesn't have a "number type" in URLs — every value here, even page and limit, arrives as text ("3", not 3), unless it was never sent at all (in which case the JS default kicks in as a real number, since 1 and 20 above are written as numeric literals). This is why Number(...) shows up repeatedly further down — the code can't assume these are already numbers.

3.3 — The base "bookable" filter

const match = { isProfileVisible: true, verificationStatus: 'approved' };

• [SE — DRY violation, flagged] This exact object appears, retyped from scratch, in getLawyerById (Block 4), getLawyerRankings (Block 5), and getLawyerAvailability (Block 7) too. It's the file's one business rule for "is this lawyer real and currently bookable?" — but it has no single shared source of truth. If that rule ever needs a 5th condition (say, isSuspended: false), a developer has to remember to update all four spots; missing one creates a real bug.

• [MongoDB] This is a filter object that will be handed to $match (3.9) — MongoDB's equivalent of a SQL WHERE clause.

3.4 — Optional-auth blocked-lawyer exclusion

if (req.user?.role === 'client') {
  const client = await Client.findOne({ userId: req.user.userId }).select('blockedLawyers');
  if (client?.blockedLawyers?.length) {
    match._id = { $nin: client.blockedLawyers };
  }
}

• [Networking — optional auth on a public route] This whole route is reachable by anonymous, logged-out visitors — nothing forces a login. So req.user might simply not exist, and every check here has to account for that explicitly rather than assuming a logged-in caller.

• [JS — optional chaining ?.] req.user?.role reads: "if req.user is null/undefined, stop right there and produce undefined — don't try to read .role off of nothing." Without ?., this would throw a TypeError and crash the request whenever there's no logged-in user. Since undefined === 'client' is simply false, the if block is just skipped for anonymous visitors — no crash, no special-casing needed.

• [Mongoose — .select()] .select('blockedLawyers') tells Mongoose to fetch only that one field (plus _id) instead of the client's entire document. This runs on every search request from a logged-in client, so keeping it minimal is worth it — there's no reason to pull someone's full profile just to check one array.

• [JS — chained optional chaining] client?.blockedLawyers?.length protects against two possible gaps: client itself could be null (defensively handled, even though it normally shouldn't be), and even if client exists, blockedLawyers could theoretically be missing. Either ?. short-circuits safely to undefined, and if (undefined) is falsy, so the block is skipped.

• [MongoDB — $nin] If the client does have blocked lawyers, match._id = { $nin: client.blockedLawyers } means "exclude any lawyer whose _id is in this list." This is the actual enforcement point of "hide blocked lawyers from search results."

• [Security] This is a server-side enforcement of a privacy preference — the client never gets a chance to see a blocked lawyer in results at all, rather than the frontend being trusted to filter them out after the fact.

3.5 — Optional filters

if (specialization) match.specialization = { $in: specialization.split(',') };
if (court) match.courtsPracticed = { $in: court.split(',') };
if (language) match.languages = { $in: language.split(',') };
if (minFee || maxFee) {
  match.consultationFee = {};
  if (minFee) match.consultationFee.$gte = Number(minFee);
  if (maxFee) match.consultationFee.$lte = Number(maxFee);
}
if (minExperience) match.yearsOfExperience = { $gte: Number(minExperience) };
if (minRating) match.rating = { $gte: Number(minRating) };

• [Networking — comma-separated multi-value convention] ?specialization=property,criminal is one common REST convention for "filter by more than one value on the same field." This code accepts a single query param and manually splits it, rather than the alternative convention of repeating the key (?specialization=property&specialization=criminal).

• [MongoDB — $in] Matches a document if its field's value overlaps with any value in the given array — so a lawyer practicing in either property or criminal law would match specialization.split(',') from that example.

• [MongoDB — $gte / $lte] "Greater than or equal" / "less than or equal." minFee and maxFee are built independently, so a caller can supply just one, both (giving a true "between X and Y" range), or neither.

• [JS — Number(...) conversions] Every one of these values arrived from req.query as text (see 3.2's networking note), so each gets explicitly converted with Number(...) before being compared numerically by MongoDB.

• [Security — gap, not present here] None of these values are clamped or bounds-checked (contrast with getLawyerRankings's limit handling in Block 5.1) — not dangerous on their own, but worth noticing as an inconsistency within the same file.

3.6 — Sort field whitelist

const sortFieldMap = {
  rating: 'rating',
  fee: 'consultationFee',
  experience: 'yearsOfExperience',
  consultations: 'totalConsultations',
};
const sortField = sortFieldMap[sortBy] || 'rating';

• [Security — whitelisting via lookup table] The tempting shortcut would be { $sort: { [sortBy]: sortOrder } } — sorting directly on whatever string the caller sent. The problem: nothing would then stop a caller from sending ?sortBy=verificationStatus or an internal field name never meant to be exposed as a sort key. sortFieldMap is a whitelist: a fixed, hand-written set of the only four acceptable values. Anything else looked up on it returns undefined.

• [JS — bracket notation with a dynamic key] sortFieldMap[sortBy] looks up a property using the value currently stored in sortBy — different from sortFieldMap.sortBy, which would look for a literal property named "sortBy" (which doesn't exist).

• [JS — || fallback, used correctly] If the lookup returns undefined (an unrecognized sortBy), || 'rating' supplies a safe default. || (not ??) is fine here because sortFieldMap[sortBy] can only ever be a real string or undefined — never a legitimate 0/''/false that || might wrongly overwrite (contrast with Block 5.3, where that distinction matters a lot).

3.7 — Sort direction

const sortOrder = order === 'asc' ? 1 : -1;

• [JS — ternary] A compact if/else that produces a value. If order === 'asc' is true, this expression is 1; otherwise -1.

• [MongoDB] MongoDB's $sort only understands 1 (ascending) / -1 (descending) — not the words "asc"/"desc" — so this line is translating the human-readable query param into what MongoDB actually expects. Anything other than exactly "asc" (a typo, or no order at all) silently falls through to -1.

3.8 — Pagination math

const skip = (Number(page) - 1) * Number(limit);

• [JS] page and limit are converted to real numbers first (see 3.2's networking note about why this matters — "3" - 1 happens to coerce to 2 automatically in JS, but relying on that inconsistently across operators like + is a well-known trap, so this code converts explicitly instead of leaning on it).

• [MongoDB/Algorithm — offset pagination] For page 1, skip = 0. For page 2 with limit = 20, skip = 20 — skip the first 20 matches, then return the next batch. This is standard offset pagination. Worth knowing as a tradeoff, not a bug: $skip gets slower the deeper you page, because MongoDB genuinely walks past every skipped document rather than jumping straight to a spot. Fine at moderate scale; a different technique (cursor-based pagination) scales better for very deep pages but is more complex.

3.9 — Building the aggregation pipeline

const basePipeline = [
  { $match: match },
  { $lookup: { from: 'users', localField: 'userId', foreignField: '_id', as: 'user' } },
  { $unwind: '$user' },
  ...(name ? [{ $match: { 'user.name': { $regex: name, $options: 'i' } } }] : []),
];

• [MongoDB — aggregation pipeline] An aggregation pipeline is a sequence of stages, each one transforming the output of the stage before it — like a factory line. This lets multi-step data processing (filtering, joining, computing) happen inside the database instead of in application code.

• [MongoDB — $match] Runs first, deliberately — narrowing the working set (and letting MongoDB use indexes) before the more expensive join happens next.

• [MongoDB — $lookup] A server-side join, conceptually like SQL's JOIN. from: 'users' is the raw MongoDB collection name (lowercase, pluralized — Mongoose's naming convention for a model called User). localField/foreignField say which fields to match on; as: 'user' names where the joined data lands. This runs as one join inside MongoDB itself, in the same query — unlike .populate() (see Block 4), which is a separate follow-up query.

• [MongoDB — $unwind] $lookup always produces an array (user: [...]), even though there's guaranteed to be exactly one matching User (the schema enforces userId: { unique: true }). $unwind flattens that single-element array into a plain object, user: {...} — which is what makes 'user.name' a valid path in the next line and in formatLawyer.

• [JS — conditional array spread] ...(name ? [{...}] : []) evaluates to either a one-element array (spread into basePipeline as a real 4th stage) or an empty array (spreading in nothing at all). This is the array equivalent of an if statement, used because you can't easily "not add an element" with a plain if inside an array literal.

• [Security — flagged, real gap] name comes straight from req.query.name and flows directly into MongoDB's $regex with no escaping. $regex interprets its input as an actual regex pattern (special characters like ., *, (, | change meaning), not plain text. A caller could craft a deliberately expensive pattern that makes MongoDB slow to evaluate against every document — a ReDoS (Regular Expression Denial of Service) risk. The fix — not present in this file — is to escape regex-special characters in name before using it, so it only ever matches literal text.

3.10 — Running both queries concurrently

const [lawyersRaw, countResult] = await Promise.all([
  Lawyer.aggregate([
    ...basePipeline,
    { $sort: { [sortField]: sortOrder } },
    { $skip: skip },
    { $limit: Number(limit) },
    { $project: { ...LAWYER_FIELDS, 'user._id': 1, 'user.name': 1 } },
  ]),
  Lawyer.aggregate([...basePipeline, { $count: 'total' }]),
]);

• [Concurrency — Promise.all] These two aggregations are independent — neither needs the other's result. Running them with two separate awaits would mean waiting for the first to fully finish before even starting the second. Promise.all([...]) starts both at roughly the same time, and the combined await resolves once both finish — total wait time is close to whichever is slower, not the sum of both.

• [JS — array destructuring of the result] Promise.all resolves to an array of results in the same order the promises were given. const [lawyersRaw, countResult] = ... pulls the first aggregation's result into lawyersRaw and the second's into countResult, purely by position.

• [JS — computed property name] { [sortField]: sortOrder } uses the value stored in sortField (e.g. "consultationFee") as the object key, not the literal text "sortField".

• [MongoDB — $sort / $skip / $limit] Order, offset, and page size, applied in that sequence.

• [Security — flagged gap] Unlike getLawyerRankings (Block 5.1), limit here is never clamped — a caller could send ?limit=999999999 and force MongoDB to try building a huge result set in one go. This is a real resource-exhaustion risk, and notably the developer clearly knows the clamping pattern (they use it elsewhere in this same file) but didn't apply it here.

• [MongoDB — $project] Spreads LAWYER_FIELDS (Block 1) plus two more dotted paths reaching into the user sub-object created by $unwind.

• [MongoDB — $count] Collapses the whole pipeline's current result set into one document, { total: <number> }. If zero documents match, the output is an empty array, not [{ total: 0 }] — which matters for the next block.

• [SE — why run this as a second, separate query] $skip/$limit only return the current page; there's no way to also learn "and there were 347 total matches" from that same query. So the file runs the filtering logic twice — once as a realized page of documents, once collapsed into a count — both starting from the identical basePipeline so they always agree on what "counts" as a match.

3.11 — Total and formatted list

const total = countResult[0]?.total || 0;
const lawyers = lawyersRaw.map(formatLawyer);

• [JS — optional chaining + || together] countResult[0] could be undefined (an empty array has no index 0, per the $count note above). ?.total safely handles that. || 0 then supplies a plain 0 if either countResult[0] was missing or .total itself was somehow falsy.

• [JS — passing a function reference to .map()] .map(formatLawyer) hands .map() the function itself (no wrapping arrow function needed), because formatLawyer already takes exactly the one argument .map() provides per element and returns exactly what's needed for each output element.

3.12 — Response

return sendSuccess(res, 200, { lawyers }, paginationMeta({ total, page, limit }));

• [SE — consistent response envelope] Every success response in the whole API funnels through sendSuccess, so every endpoint's response has the same overall shape regardless of which handler produced it.

• [Networking — pagination metadata] lawyers alone wouldn't tell a frontend how many total matches exist or which page it's viewing. paginationMeta({ total, page, limit }) builds that context so a UI can render something like "Page 2 of 18."

Block 4 — exports.getLawyerById

exports.getLawyerById = asyncHandler(async (req, res) => {
  const lawyer = await Lawyer.findOne({
    _id: req.params.id,
    isProfileVisible: true,
    verificationStatus: 'approved',
  })
    .populate('userId', 'name')
    .lean();

  if (!lawyer) {
    throw new AppError('Lawyer not found.', 404);
  }

  const formatted = formatLawyer({ ...lawyer, user: lawyer.userId });

  let isSaved = false;
  let isBlocked = false;
  if (req.user) {
    const client = await Client.findOne({ userId: req.user.userId });
    if (client) {
      isSaved = client.savedLawyers.some((id) => id.equals(lawyer._id));
      isBlocked = client.blockedLawyers.some((id) => id.equals(lawyer._id));
    }
  }

  return sendSuccess(res, 200, { lawyer: formatted, isSaved, isBlocked });
});

• [SE — same DRY gap as 3.3] The isProfileVisible: true, verificationStatus: 'approved' filter is retyped here, identically, for the second of four times in this file.

• [Mongoose — .findOne() + .populate()] Lawyer documents store userId as just a reference (an ObjectId) to a separate User document. .populate('userId', 'name') tells Mongoose "also fetch that referenced User and swap the raw ID for the actual object (just its name field)." This runs as a separate second query under the hood — a reasonable cost for one document, but not something you'd want per-item in a list (see 3.9's $lookup note for why lists use aggregation instead).

• [Mongoose — .lean()] Without .lean(), a Mongoose query result is wrapped in a full Document instance (with .save(), change tracking, etc.) — overhead this handler never needs, since it only reads and reshapes data, never writes it back. .lean() returns a plain object instead, skipping that machinery.

• [Security — information hiding via identical errors] Two very different situations — "this _id doesn't exist at all" and "this _id exists but the lawyer is unapproved/hidden" — both make lawyer come back null here, because the visibility filter is baked into the same findOne call as the _id check. Both produce the exact same 404. This deliberately prevents an outside visitor from being able to tell "no such lawyer" apart from "that lawyer is suspended," which would otherwise leak information about lawyer status.

• [Networking — 404 semantics] 404 here means "not found from this caller's point of view" — a deliberate, security-motivated use of the status code (contrast with the 400s in toUtcMidnight, Block 6, which mean "you sent something malformed").

• [JS — object spread with key override] { ...lawyer, user: lawyer.userId } copies every property off lawyer into a new object, then adds/overwrites a user key pointing at lawyer.userId — because formatLawyer expects a user key, but after .populate() the populated data actually sits under userId (matching the schema's own field name). Because user: lawyer.userId is written after the spread, it wins if there was any conflict. The original lawyer object is never mutated — spread always builds a new object.

• [JS — let vs const] isSaved/isBlocked start as false but might get reassigned below depending on login state — const would be a syntax error here since reassignment is exactly what happens.

• [Networking — optional auth] if (req.user) — this route works for anonymous visitors too; personalization (isSaved/isBlocked) only happens for logged-in callers.

• [JS — Array.prototype.some()] Runs a test against every array element and returns true the moment any element passes (stopping early once it finds a match). Here: "does this client's saved/blocked list contain this lawyer's ID?"

• [Mongoose — ObjectId.equals(), not ===] MongoDB IDs are objects, not primitives — two ObjectId instances representing the same underlying ID are still different objects in memory, so === between them is false even for a genuine match (and .includes() would break the same way, since it uses === internally). .equals() does a real value comparison instead. Always use .equals() for ObjectId comparisons in Mongoose, never === or .includes().

• [SE — reused formatLawyer] Same shared function from Block 2, guaranteeing this response's lawyer field looks identical in shape to what getLawyers returns.

Block 5 — exports.getLawyerRankings

5.1 — Setup and clamped pagination

const { specialization, page = 1, limit = 50 } = req.query;
const pageNumber = Math.max(1, Number(page) || 1);
const limitNumber = Math.min(100, Math.max(1, Number(limit) || 50));

• [Security — clamping, done right here] Unlike getLawyers (3.10), limitNumber is explicitly bounded between 1 and 100 no matter what the caller sends — ?limit=999999999 can't force a huge query here. Math.max(1, ...) prevents 0 or negative values; Math.min(100, ...) prevents excessively large ones.

• [JS] Number(limit) || 50 falls back to 50 if Number(limit) is NaN (e.g. someone sent ?limit=abc) — NaN is falsy, so || catches that case too, on top of the destructuring default only covering a totally missing param.

5.2 — Match filter and base pipeline

const match = { isProfileVisible: true, verificationStatus: 'approved' };
if (specialization) match.specialization = { $in: specialization.split(',') };

const basePipeline = [
  { $match: match },
  { $lookup: { from: 'users', localField: 'userId', foreignField: '_id', as: 'user' } },
  { $unwind: '$user' },
];

• [SE — the DRY gap again] Third appearance of the bookable filter, retyped from scratch.

• Same $match / $lookup / $unwind mechanics as Block 3.9, minus the name-regex stage (this endpoint doesn't support name search).

5.3 — Getting the value range and total, concurrently

const [rangeResult, countResult] = await Promise.all([
  Lawyer.aggregate([
    { $match: match },
    { $group: { _id: null, min: { $min: '$totalConsultations' }, max: { $max: '$totalConsultations' } } },
  ]),
  Lawyer.aggregate([{ $match: match }, { $count: 'total' }]),
]);

const total = countResult[0]?.total || 0;
const range = rangeResult[0];
const minConsultations = range?.min ?? 0;
const maxConsultations = range?.max ?? 0;
const flatVolume = maxConsultations === minConsultations;

• [Concurrency] Same Promise.all reasoning as 3.10 — the min/max computation and the total count don't depend on each other, so both run at once.

• [MongoDB — $group with _id: null] Normally $group buckets documents by some field's distinct values. _id: null means "don't bucket at all — collapse every matched document into one single group," which is what lets $min/$max compute across the entire matched set at once.

• [MongoDB — $min / $max accumulators] Computed inside the database, in one pass, across every matched document — far cheaper than pulling every lawyer's raw totalConsultations back to the app server just to run Math.min/Math.max in JavaScript.

• [JS — nullish coalescing ??, not ||] This is the one spot in the file where the ?? vs || distinction genuinely matters: if a brand-new approved lawyer has done zero consultations, range.min could legitimately be 0 — a real, meaningful value, not "missing data." || would treat that 0 as falsy and wrongly try to replace it; ?? only falls back when the value is truly null/undefined (i.e., range itself is undefined because zero lawyers matched at all). Compare this directly with 3.6, where || was the right tool — same operator family, opposite correctness depending on whether 0 can be a legitimate value.

• [Algorithm — division-by-zero guard] flatVolume precomputes whether max === min (every matched lawyer tied, or only one/zero matched) before the next block's formula would otherwise divide by (max - min) = 0. This is checked deliberately rather than letting the pipeline silently produce NaN/Infinity.

5.4 — Skip, and the scoring pipeline

const skip = (pageNumber - 1) * limitNumber;

const rankingsRaw = await Lawyer.aggregate([
  ...basePipeline,
  {
    $addFields: {
      ratingScore: { $cond: [{ $gt: ['$rating', 0] }, { $divide: ['$rating', 5] }, 0] },
      volumeScore: flatVolume
        ? 0.5
        : { $divide: [{ $subtract: ['$totalConsultations', minConsultations] }, { $subtract: [maxConsultations, minConsultations] }] },
    },
  },
  {
    $addFields: {
      score: { $multiply: [{ $add: [{ $multiply: [0.4, '$ratingScore'] }, { $multiply: [0.6, '$volumeScore'] }] }, 100] },
    },
  },
  { $sort: { score: -1, rating: -1, totalConsultations: -1, _id: 1 } },
  { $skip: skip },
  { $limit: limitNumber },
  { $project: { ...LAWYER_FIELDS, 'user._id': 1, 'user.name': 1, score: 1 } },
]);

• [MongoDB — $cond] [condition, thenValue, elseValue]. ratingScore reads: "if rating > 0, compute rating / 5; otherwise 0." (Mathematically 0 / 5 is also 0, so the guard is somewhat redundant here — but it states the intent explicitly rather than relying on that coincidence.)

• [Algorithm — min-max normalization] volumeScore's formula, when not flat, is (totalConsultations - min) / (max - min) — the standard way to rescale any raw number into a fair 0–1 range relative to the current matched set. When flatVolume is true, everyone instead gets a neutral 0.5 — the mathematically honest answer when there's no real variation to normalize against.

• [MongoDB — $divide / $subtract / $multiply / $add] MongoDB's aggregation syntax for ordinary arithmetic, written as { $operator: [a, b] } instead of a - b etc., computed per-document, inside the database.

• [MongoDB — two sequential $addFields stages] The second stage's score formula references '$ratingScore' and '$volumeScore', both defined by the first stage. Fields being computed within a single $addFields stage generally can't reliably reference each other yet — splitting into two stages guarantees stage 1 fully finishes and attaches both scores before stage 2 reads them.

• [Algorithm — weighted composite score] score = (0.4 * ratingScore + 0.6 * volumeScore) * 100 — two 0–1 sub-scores combined with explicit weights (40% rating, 60% volume) and scaled to a friendlier 0–100 range.

• [Algorithm — multi-key deterministic sort] { score: -1, rating: -1, totalConsultations: -1, _id: 1 } sorts by score first, but if two lawyers tie exactly, falls through to rating, then totalConsultations, then finally _id — which is guaranteed unique, so this last tiebreaker eliminates all possible ties. Without a fully deterministic sort, tied documents' relative order across separate page-1/page-2 requests would technically be unspecified — meaning a lawyer could seem to vanish or duplicate between pages purely due to how MongoDB happened to break the tie that time.

• [MongoDB — $skip/$limit/$project] Same mechanics as Block 3.10, with score: 1 added to the projection so it survives into the output.

5.5 — Shaping and responding

const rankings = rankingsRaw.map((raw, index) => ({
  rank: skip + index + 1,
  score: Math.round(raw.score * 10) / 10,
  lawyer: formatLawyer(raw),
}));

return sendSuccess(res, 200, { rankings }, paginationMeta({ total, page: pageNumber, limit: limitNumber }));

• [JS — .map()'s second index argument] .map()'s callback receives the current element's position (0-based) as a second parameter.

• [Algorithm — global rank under pagination] skip + index + 1 converts "this lawyer's position within the current page" into "this lawyer's position across the entire sorted dataset." This only works because the sort (5.4) ran on the whole matched set before $skip/$limit narrowed it down — sort first, paginate second. The +1 exists because ranks conventionally start at 1, not 0.

• [JS — multiply/round/divide for decimal precision] Math.round() only rounds to whole numbers — there's no built-in "round to 1 decimal" in plain JS. Multiplying by 10 first, rounding, then dividing by 10 again is the standard workaround (e.g. 87.36 → 873.6 → 874 → 87.4).

• [SE] Same shared sendSuccess/paginationMeta/formatLawyer reuse as the earlier handlers.

Block 6 — toUtcMidnight(dateInput) (date helper)

function toUtcMidnight(dateInput) {
  const d = new Date(dateInput);
  if (Number.isNaN(d.getTime())) {
    throw new AppError('Invalid date.', 400);
  }
  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
}

• [Date/Time — Date leniency and Invalid Date] JavaScript's Date constructor is very forgiving about input formats, but when it genuinely can't parse something, it doesn't throw — it silently produces an Invalid Date: an object that looks like a normal Date but represents no real point in time.

• [JS — detecting it correctly with Number.isNaN] d.getTime() returns NaN for an Invalid Date. You can't check this with d.getTime() === NaN — by a quirk of the underlying numeric standard, NaN never equals anything, including itself. Number.isNaN(...) is the built-in function specifically designed to detect this correctly.

• [SE — AppError] Throwing new AppError('Invalid date.', 400) lets this single throw carry both a message and an HTTP status code, which the asyncHandler wrapper (Block 3.1) routes to Express's central error handler — no manual res.status(400).json(...) needed here.

• [Date/Time — timezone normalization to UTC midnight] Date.UTC(year, month, day) builds a timestamp for exactly midnight UTC on a given calendar date, discarding whatever time-of-day or timezone the original input carried. This matches how Availability documents store their own date field. Because MongoDB date comparisons are exact timestamp comparisons — not "same calendar day, loosely interpreted" — a raw, un-normalized date like 2026-07-20T15:30:00+05:30 would not equal 2026-07-20T00:00:00.000Z, and a query using it as-is would silently fail to match documents the caller clearly meant. This function guarantees every date this file uses lines up with that storage convention, regardless of how the caller originally formatted it.

• [JS — pure function] Same input always produces the same output (or the same thrown error) — no side effects, safe to call from multiple places (it's used twice in Block 7).

Block 7 — exports.getLawyerAvailability

7.1 — Confirming the lawyer is bookable

const lawyer = await Lawyer.findOne({
  _id: req.params.id,
  isProfileVisible: true,
  verificationStatus: 'approved',
});
if (!lawyer) {
  throw new AppError('Lawyer not found.', 404);
}

• [SE — fourth appearance of the DRY gap] Same bookable filter, retyped a fourth time.

• [Security — same identical-error info hiding as Block 4] "Doesn't exist" and "exists but not bookable" again produce the same 404 here.

7.2 — Date range, with validation

const { from, to } = req.query;
const fromDate = from ? toUtcMidnight(from) : toUtcMidnight(new Date());
const filter = { lawyerId: lawyer._id, date: { $gte: fromDate } };
if (to) {
  const toDate = toUtcMidnight(to);
  if (toDate < fromDate) {
    throw new AppError('to must be on or after from.', 400);
  }
  filter.date.$lte = toDate;
}

• [Date/Time] If from isn't supplied, it defaults to today (normalized via Block 6), not "the beginning of time" — a sensible default for a booking feature, since you can't book a slot in the past.

• [MongoDB — $gte/$lte again, this time on dates] Same range-filter pattern as Block 3.5, applied to date instead of consultationFee.

• [SE — explicit validation instead of a silently empty result] Without the toDate < fromDate check, sending an impossible range (to before from) would just make MongoDB return zero results — indistinguishable, from the caller's side, from "no availability in a perfectly valid range." This code deliberately catches the nonsensical input before querying and returns a clear 400, rather than letting a bug hide behind an innocent-looking empty array.

• [Networking — 400 here, not 404] This is a genuinely malformed/logically-invalid request (the client should change what it sent), which is exactly what 400 conventionally signals — contrast with the 404s in 7.1 and Block 4, which mean "the request was fine, but the resource doesn't exist/isn't visible."

7.3 — Fetching and reshaping

const availabilityDocs = await Availability.find(filter).sort({ date: 1 }).lean();
const now = new Date();

const availability = availabilityDocs
  .map((doc) => ({
    availabilityId: doc._id,
    date: doc.date,
    slots: doc.slots
      .filter((slot) => !slot.isBooked && new Date(slot.startTime) > now)
      .map((slot) => ({ slotId: slot._id, startTime: slot.startTime, endTime: slot.endTime })),
  }))
  .filter((day) => day.slots.length > 0);

return sendSuccess(res, 200, { availability });

• [Mongoose — .lean() again] Same reasoning as Block 4 — this is a pure read, so there's no need for the full Document machinery.

• [Date/Time — capturing now once] now is captured a single time before filtering starts, rather than calling new Date() fresh inside the loop for every slot — slightly more efficient, and avoids any inconsistency if the loop somehow spanned real time.

• [JS — chained .map().filter().map().filter()] Read top to bottom as a pipeline:

  1. Outer .map() — for each Availability document (one per calendar day), build a new object with a renamed availabilityId and a slots array that's itself the result of steps 2–3.

  2. Inner .filter() — keep only slots where !slot.isBooked (not taken) and new Date(slot.startTime) > now (still in the future) — both must be true.

  3. Inner .map() — rebuild each surviving slot with exactly three fields.

  4. Outer .filter() — after the outer .map() finishes, drop any day whose slots array ended up empty, so the response doesn't include clutter like { date: ..., slots: [] }.

• [Date/Time — "only future" filtering] new Date(slot.startTime) > now works because JS automatically converts Date objects to their millisecond-timestamp numbers for comparison — so this really means "is this slot's timestamp later than the current timestamp."

• [Security — excluding internal fields] The inner .map() deliberately builds a brand-new object with only slotId/startTime/endTime — leaving out the raw slot's bookingId, which would otherwise reveal internal booking-record identifiers to an anonymous browsing visitor with no legitimate reason to see them. Same principle as LAWYER_FIELDS (Block 1), applied to a different data shape.

• [SE] Final response again goes through the shared sendSuccess envelope.