Login
login authenticates a user with their email and password and returns a fresh JWT token plus the matching user document. It is the first act of the Auth & Users chapter because every protected act in the app requires a token header that only login can produce. It belongs to the user model and is the only user act without a preAct chain — you don't need a token to get one.
Get Me
getMe returns the currently authenticated user — the one whose token you sent — without needing any set fields. It's the fastest way for a client to hydrate its own profile (name, roles, features, units) right after login. It belongs to the user model and is the canonical example of reading the request context that setTokens and setUser built for you.
Get One User
getUser fetches a single user document by _id. Unlike getMe (which returns the caller), getUser can fetch any user the caller is allowed to see — managers use it to inspect a team member, admins use it to view a profile before editing. It belongs to the user model and is the first act here that runs the full preAct chain including grantAccess.
Get Users
getUsers returns a paginated, searchable, sortable list of users — the backbone of the admin "user management" screen. It supports full-text search on firstname / lastname / email (powered by the text index createUserTextIndex creates at boot), filtering by role, sorting by relevance or any listed field, and pagination. It belongs to the user model.
Count Users
countUsers returns the number of users that match an optional search term — no documents, just a number. It exists to back pagination: a list UI calls getUsers for the page of rows and countUsers (with the same search) for the total, so it can render the page count. It belongs to the user model.
Add User
addUser creates a new user: it hashes the password, writes the pure fields, and wires up the avatar, organizations, and units relations in one call. It belongs to the user model and is the most relation-heavy write act in the auth chapter — the place to study how insertOne with a relations object works.
Update User
updateUser edits the scalar (pure) fields of an existing user — name, email, position, isActive, features, and optionally the password (which is re-hashed). It deliberately does not touch relations; those are handled by the sibling act updateUserRelations. It belongs to the user model.
Update User Relations
updateUserRelations replaces the avatar, organizations, and units relations on an existing user — the relational counterpart to updateUser, which only edits scalar fields. It's the place to study user.addRelation with replace how one act rewrites a single relation, a many-relation, or all three at once, keeping reverse snapshots in sync. It belongs to the user model.
Remove User
removeUser deletes a user document by _id. It belongs to the user model and is the destructive end of the CRUD pair with addUser. In this app it's a hard delete — reserved for Manager/Admin — because other models reference users by relation snapshots rather than foreign keys.
Dashboard Statistic
dashboardStatistic is the act that powers the admin dashboard. It runs several independent MongoDB aggregations in parallel across purchaseOrder, stepApproval, budgetLine, inventory, and stockMovement, and returns only the slices the client asked for in get. It belongs to the user model (it's about the logged-in user's view of the system) and is the best example in the app of client-driven aggregation selection plus role-scoped data visibility.
Auth Utilities
Every protected act in this app shares one preAct chain — setTokens → setUser → grantAccess(...) — plus a set of supporting helpers for tokens, passwords, feature checks, and context typing. All of them live in examples/advanced-tutorial/utils/ and are re-exported from the @lib barrel (utils/mod.ts). This page explains each one, in the order the request pipeline hits them.