app/Order/
├── actions/         # real-time API handlers (V1Create, V1Update, …)
├── tasks/           # background jobs (V1ExportTask, …)
├── tests/           # integration + task + unit tests
├── languages/       # i18n strings (en.js, …)
├── mailers/         # email templates
├── controller.js    # thin router: request → correct action
├── model.js         # Sequelize table definition
├── routes.js        # feature routes
├── error.js         # feature error codes
├── helper.js        # feature-local helpers
└── worker.js        # registers which task handles which job

repo root
├── app/                  # ★ ALL features live here — one folder per feature (see §4)
│
├── index.js              # web entry point → boots server.js (clustered via throng)
├── server.js             # builds the Express app: middleware, routes, socket, error handler
├── worker.js             # worker entry point — registers every queue's task processors (§9)
├── cronjobs.js           # cron entry point — schedules jobs on a clock (§9)
├── routes.js             # GLOBAL route aggregator — mounts every feature's routes.js
├── models.js             # GLOBAL model aggregator — scans app/*/model.js into one `models` object
│
├── middleware/           # global Express middleware (id, args, auth, error, exit) — runs on every request (§5)
├── services/             # global SERVICES — third-party wrappers + big shared infra (see below)
├── helpers/              # global HELPERS — small pure functions shared across features (see below)
│
├── database/             # everything about the DB except the per-feature models
│   ├── schema.sql        #   human-readable documentation of every table (never executed)
│   ├── sequence.js       #   the ORDER tables are created in (FK deps) — generator updates it, never by hand
│   ├── seed/             #   dev seed data (set1/…) loaded by `yarn seed`
│   ├── backups/          #   DB dumps from `yarn backup`; `yarn restore` reads these
│   └── index.js          #   the Sequelize connection
├── migrations/           # the real, ordered schema changes applied by `yarn migrate` (§7)
├── models/               # (essentially empty — models live in app/*/model.js; models.js aggregates them)
│
├── languages/            # GLOBAL i18n source strings (en.js, …) — compiled into locales/ (§8)
├── locales/              # COMPILED i18n output (generated by `yarn lang` — never edit by hand)
├── mailers/              # GLOBAL email templates (feature-specific ones live in app//mailers/)
│
├── config/               # per-environment .env files (gitignored) + config glue (§3)
├── docs/                 # all the deep docs (conventions.txt, workflow.md, auth-migration.md, …)
├── scripts/              # standalone scripts you run by hand (e.g. compile-lang, password helpers)
├── redis/                # project-local Redis build (gitignored; local dev only — §3)
│
├── test/                 # global test entry: stitches feature tests + holds fixtures, helper/service tests
│   ├── app/              #   stitches together each feature folder's tests
│   ├── fixtures/         #   test-DB baseline data (fix1/…) — the test analog of database/seed
│   ├── helpers/          #   unit tests for GLOBAL helpers
│   └── services/         #   unit tests for GLOBAL services
│
├── public/  views/       # static assets & server-rendered views (e.g. email preview)
└── AGENTS.md  CLAUDE.md   # agent guides (see §15)

config/.env.development
config/.env.test
config/.env.production   # only if connecting to prod locally
config/.env.staging      # (staging is just a second "production" app)

# create the dev and test databases in Postgres, e.g.
createdb nitrabrain_dev
createdb nitrabrain_test

yarn migrate     # run all pending migrations (dev)
yarn seed        # optional: load dev seed data

yarn redis       # start project-local Redis (separate terminal)
yarn s           # web/API server
yarn w           # background worker
yarn cron        # clock / cronjobs

yarn test                                  # full suite (compiles i18n + fixtures first)
npx jest app/Admin/tests --runInBand       # a subset

app/Order/
├── actions/
│   ├── index.js          # auto-managed aggregator (don't edit by hand)
│   ├── V1Create.js       # one file per action
│   └── V1Query.js
├── tasks/
│   ├── index.js          # auto-managed aggregator
│   └── V1ExportTask.js   # one file per background task
├── tests/
│   ├── integration/      # one test per action (real HTTP)
│   ├── tasks/            # one test per task
│   └── helper.test.js    # unit tests for helper.js
├── languages/en.js       # i18n strings for this feature
├── mailers/              # email templates (index.ejs)
├── model.js              # the Sequelize table definition
├── routes.js             # this feature's routes
├── controller.js         # thin router: request → correct action
├── error.js              # this feature's error codes
├── helper.js             # feature-local helper functions
└── worker.js             # maps job names → task functions

yarn gen Order                 # whole feature folder (singular PascalCase name)
yarn gen Order -a V1Create     # add an action (+ its test, updates actions/index.js)
yarn gen Order -t V1ExportTask # add a task (+ its test, updates tasks/index.js)
yarn gen Order -m Confirmation # add a mailer
yarn del Order [-a|-t|-m ...]  # the reverse

// index.js — each clustered worker (throng) registers the signal handlers after it starts listening
server.listen(PORT, () => {
  process.on('SIGTERM', async () => await gracefulExit(server)); // deploy / restart / kill
  process.on('SIGINT',  async () => await gracefulExit(server)); // Ctrl-C in dev
});

// middleware/exit.js — drain in order, then exit
async function gracefulExit(server) {
  if (isShuttingDown) return;   // re-entrant guard (two signals won't double-run it)
  isShuttingDown = true;        // from now on exit.middleware answers new requests with 503

  // safety net: if draining hangs, force-exit after 30s so the platform doesn't SIGKILL mid-write
  setTimeout(() => process.exit(1), 30000);

  await queue.closeAll();   // stop pulling/queuing background jobs
  await socket.close();     // close socket.io connections
  await models.db.close();  // close the Sequelize (Postgres) pool
  server.close(() => process.exit(0)); // stop accepting connections, then exit clean once in-flight requests finish
}

// app/Order/routes.js — lowercase, no separators; registered into the global routes.js
router.all('/v1/orders/update', controller.V1Update);

// app/Order/controller.js — pick the action by role, send the action's object as the response
async function V1Update(req, res, next) {
  let method = null;

  // pick the action based on who is calling
  if (req.admin) {
    method = 'V1UpdateByAdmin';
  } else if (req.user) {
    method = 'V1UpdateByUser';
  } else {
    return res.status(401).json(errorResponse(req, ERROR_CODES.UNAUTHORIZED));
  }

  try {
    const result = await actions[method](req, res);
    return res.status(result.status).json(result);
  } catch (error) {
    // hand off to middleware/error.js — never return res.status(500) yourself
    return next(error);
  }
} // END V1Update

// controller.js — branch on role AND device
async function V1Sync(req, res, next) {
  let method = null;

  if (req.user) {
    // req.device is resolved from a client header (see §11 — explained later)
    if (req.device === 'MOBILE') {
      method = 'V1SyncByUserOnMobile';
    } else {
      method = 'V1SyncByUserOnWeb';
    }
  } else {
    return res.status(401).json(errorResponse(req, ERROR_CODES.UNAUTHORIZED));
  }

  try {
    const result = await actions[method](req, res);
    return res.status(result.status).json(result);
  } catch (error) {
    return next(error);
  }
} // END V1Sync

/**
 * Header comment — what this file is
 */

'use strict'; // strict mode, always first

// env (only where a file reads process.env directly)
const { NODE_ENV } = process.env;

// built-in node modules
const path = require('path');
const crypto = require('crypto');

// third-party modules
const joi = require('joi');
const moment = require('moment');

// services (app/../services) — note: the queue SERVICE is required here
const queue = require('../../../services/queue');
const { errorResponse, ERROR_CODES } = require('../../../services/error');

// helpers (app/../helpers)
const { getOffset } = require('../../../helpers/cruqd');

// models (the Sequelize models)
const models = require('../../../models');

// queues — grab the queue INSTANCES right after models (queue.js itself lives in services above)
const OrderQueue = queue.get('OrderQueue');

// module-level constants (UPPER_CASE)
const DEFAULT_LIMIT = 25;

// module.exports BEFORE the implementations — a table of contents for the file
module.exports = {
  V1ReadByUser
};

/**
 * Each method is defined below, in the same order as module.exports.
 */
async function V1ReadByUser(req, res) {
  // ...
} // END V1ReadByUser

/**
 * Read and return an order
 *
 * GET/POST /v1/orders/read
 * Must be logged in · Roles: ['user']
 *
 * req.args = { @id - (STRING - REQUIRED): the order id }
 * Success: returns the order
 * Errors:
 *   400: BAD_REQUEST_INVALID_ARGUMENTS
 *   404: ORDER_NOT_FOUND_ORDER_DOES_NOT_EXIST
 */
async function V1ReadByUser(req, res) {
  // i18n: a locale-aware translator for user-facing strings. In an HTTP action you
  // normally use req.__('KEY') (locale auto-set by middleware); getLocalI18n() gives
  // you a standalone instance for places without a req (covered more in §8).
  const i18n = lang.getLocalI18n();

  // 1. validate req.args with Joi
  const schema = joi.object({
    id: joi.string().uuid().required()
  });

  const { error, value } = schema.validate(req.args);

  if (error) {
    return errorResponse(req, ERROR_CODES.BAD_REQUEST_INVALID_ARGUMENTS, joiErrorsMessage(error));
  }

  req.args = value; // Joi has now coerced types ('5' -> 5, 'true' -> true)

  try {
    // 2. business logic — scope to the owner; exclude sensitive fields
    const order = await models.order.findOne({
      where: {
        id: req.args.id,
        userId: req.user.id
      },
      attributes: {
        exclude: models.order.getSensitiveData()
      }
    });

    if (!order) {
      return errorResponse(req, ERROR_CODES.ORDER_NOT_FOUND_ORDER_DOES_NOT_EXIST);
    }

    // 3. flat success response
    return {
      status: 200,
      success: true,
      order: order.dataValues
    };
  } catch (error) {
    // hand off to the controller -> error middleware (never return res.status(500))
    throw error;
  }
} // END V1ReadByUser

async function V1UpdateByUser(req, res) {
  // ...validate req.args with Joi (same as the read above)...

  // open a transaction: every write below either all commits or all rolls back
  const t = await models.db.transaction();

  try {
    // load the row, scoped to the caller (req.user — courtesy of the auth middleware)
    const order = await models.order.findOne({
      where: {
        id: req.args.id,
        userId: req.user.id
      },
      transaction: t
    });

    if (!order) {
      // roll back before returning an error from inside a transaction
      await t.rollback();
      return errorResponse(req, ERROR_CODES.ORDER_NOT_FOUND_ORDER_DOES_NOT_EXIST);
    }

    // pure logic lives in helper.js — no DB, no req — so it's trivial to unit-test (see §12)
    const nextStatus = helper.computeNextStatus(order.status, req.args.action);

    // the actual DB write, inside the transaction
    await order.update({ status: nextStatus }, { transaction: t });

    // commit FIRST — nothing below should observe an uncommitted row
    await t.commit();

    // enqueue slow follow-up work as a background job (the worker runs it) — see §9
    await OrderQueue.add('V1SendReceiptTask', {
      orderId: order.id
    });

    // push a real-time update to connected clients — ALWAYS after commit — see §10
    socket.getIO()
      .to(`${SOCKET_ROOMS.USER}${socketWrapper(req.user.id)}`)
      .emit(SOCKET_EVENTS.ORDER_UPDATED, { id: order.id, status: nextStatus });

    // flat success response
    return {
      status: 200,
      success: true,
      order: order.dataValues
    };
  } catch (error) {
    // on any throw, roll the transaction back, then let it propagate to the error middleware
    await t.rollback();
    throw error;
  }
} // END V1UpdateByUser

// 201 — created a new record
return {
  status: 201,
  success: true,
  order: newOrder
};

// 202 — accepted, work continues in a background job
return {
  status: 202,
  success: true,
  jobId: job.id
};

// 200 — default (e.g. a list/query)
return {
  status: 200,
  success: true,
  orders: rows,
  total: count
};

// only the two role methods are exported — the controller calls these
module.exports = {
  V1CreateByUser,
  V1CreateByAdmin
};

// PUBLIC: user entry point — does the user-specific bit, then delegates
async function V1CreateByUser(req, res) {
  // ...user-only validation / defaults...
  return V1Create(req, { isAdmin: false });
} // END V1CreateByUser

// PUBLIC: admin entry point — does the admin-specific bit, then delegates
async function V1CreateByAdmin(req, res) {
  // ...admin-only validation / extra fields...
  return V1Create(req, { isAdmin: true });
} // END V1CreateByAdmin

// PRIVATE: the 90% shared logic. NOT in module.exports, NOT called by the controller.
// This is where the real work lives — kept in the action file, just not exported.
async function V1Create(req, { isAdmin }) {
  // ...validate, transaction, write, queue, socket — the bulk of the action...
  return {
    status: 201,
    success: true,
    order: newOrder
  };
} // END V1Create

async function V1QueryByUser(req, res) {
  const schema = joi.object({
    page:  joi.number().integer().min(1).default(1),    // which page (1-based)
    limit: joi.number().integer().min(1).max(100).default(25), // rows per page — capped at 100
    sort:  joi.string().default('-startTime'),          // comma-list of columns; '-' = descending
    status: joi.string().optional()                     // a comma-separated LIST, e.g. 'PENDING,CONFIRMED'
  });

  const { error, value } = schema.validate(req.args);

  if (error) {
    return errorResponse(req, ERROR_CODES.BAD_REQUEST_INVALID_ARGUMENTS, joiErrorsMessage(error));
  }

  req.args = value;

  try {
    // SECURITY: always scope the list to the owner — never return another user's rows.
    // The flattened owner FK (§7) makes this a flat, indexed filter.
    const where = { userId: req.user.id };

    // turn a 'PENDING,CONFIRMED' list arg into  status: { [Op.in]: ['PENDING','CONFIRMED'] }
    convertStringListToWhereStmt(where, req.args, [
      { name: 'status', col: 'status' }
    ]);

    const { count, rows } = await models.booking.findAndCountAll({
      where,
      order: getOrdering(req.args.sort), // '-startTime' → [['startTime','DESC']]
      limit: req.args.limit,
      offset: getOffset(req.args.page, req.args.limit),
      attributes: {
        exclude: models.booking.getSensitiveData()
      }
    });

    // flat response: name the array after the content, include the paging metadata
    return {
      status: 200,
      success: true,
      bookings: rows,
      total: count,
      page: req.args.page,
      limit: req.args.limit
    };
  } catch (error) {
    throw error;
  }
} // END V1QueryByUser

const sensitiveData = ['salt', 'password', 'passwordResetToken']; // never exposed to anyone
const privateData = sensitiveData.concat(['phone', 'birthdate']); // private between users

module.exports = (sequelize, DataTypes) => {
  const Order = sequelize.define('order', {
    id: {
      type: DataTypes.UUID,
      allowNull: false,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
      validate: {
        isUUID: 4
      }
    },

    // foreign keys are declared in associate(), not here

    status: {
      type: DataTypes.ENUM(...ORDER_STATUSES),
      allowNull: false,
      defaultValue: 'PENDING'
    },

    isPaid: {
      type: DataTypes.BOOLEAN,
      allowNull: false,
      defaultValue: false
    }
  }, {
    timestamps: true,        // auto-manage createdAt / updatedAt columns
    paranoid: true,          // soft delete: destroy() sets deletedAt instead of a real DELETE
    // freezeTableName: stop Sequelize from auto-pluralizing the model name into the table name.
    // We name the table explicitly via tableName below, so freezing keeps it exactly as written.
    freezeTableName: true,
    tableName: 'Orders',     // the real table name — PascalCase, plural

    // sensitive fields excluded from every query automatically (unless you opt back in)
    defaultScope: {
      attributes: {
        exclude: sensitiveData
      }
    },

    // always index foreign keys; named {Table}_{col}_{idx|unique}, mirrored in the migration
    indexes: [
      { name: 'Orders_userId_idx', fields: ['userId'] }
    ]
  });

  // associate(): this is the FOREIGN KEY section. Sequelize calls it after all models load,
  // so you can reference other models here. Declare every relationship + its FK column in here
  // (NOT in the attributes block above), each with an explicit onDelete/onUpdate.
  Order.associate = models => {
    Order.belongsTo(models.user, {
      as: 'user',
      foreignKey: {
        name: 'userId',      // creates the userId FK column on Orders
        allowNull: false
      },
      onDelete: 'CASCADE',   // delete the user → their orders go too
      onUpdate: 'CASCADE'
    });
  };

  // extra model functions: small helpers attached to the model so callers don't hardcode the lists.
  // e.g. actions do attributes: { exclude: models.order.getSensitiveData() }. Add getPrivateData()
  // here too if the table has fields that are private between users.
  Order.getSensitiveData = () => sensitiveData;

  return Order;
};

// helpers/constants.js
module.exports = {
  // object (singular) — reference a value by name: BOOKING_STATUS.CONFIRMED
  BOOKING_STATUS: {
    PENDING: 'PENDING',
    CONFIRMED: 'CONFIRMED',
    CANCELLED: 'CANCELLED'
  },

  // array (plural) — feed Sequelize ENUM(...) and Joi .valid(...)
  BOOKING_STATUSES: ['PENDING', 'CONFIRMED', 'CANCELLED']
};

// in the model
status: {
  type: DataTypes.ENUM(...BOOKING_STATUSES),
  defaultValue: BOOKING_STATUS.PENDING
}

// in an action's Joi schema
status: joi.string().valid(...BOOKING_STATUSES)

// .sequelizerc
const path = require('path');
module.exports = {
  config: path.resolve('config', 'config.js')
};

// config/config.js — used ONLY by the Sequelize CLI (migrations), not at runtime
const path = require('path');
const { NODE_ENV } = process.env;

// load the matching env file so DATABASE_URL is populated when you run a CLI command
if (NODE_ENV === undefined || NODE_ENV === 'development')
  require('dotenv').config({ path: path.join(__dirname, '.env.development') });
else if (NODE_ENV === 'test')
  require('dotenv').config({ path: path.join(__dirname, '.env.test') });

module.exports = {
  development: { use_env_variable: 'DATABASE_URL', dialect: 'postgres', dialectOptions: { decimalNumbers: true } },
  test:        { use_env_variable: 'DATABASE_URL', dialect: 'postgres', dialectOptions: { decimalNumbers: true } },
  production:  { use_env_variable: 'DATABASE_URL', dialect: 'postgres', ssl: true, dialectOptions: { decimalNumbers: true, ssl: { required: true, rejectUnauthorized: false } } }
};

// app/Admin/error.js  (grouped by the action that owns them)
const LOCAL_ERROR_CODES = {
  // V1Login
  ADMIN_BAD_REQUEST_INVALID_LOGIN_CREDENTIALS: {
    error: 'ADMIN.BAD_REQUEST_INVALID_LOGIN_CREDENTIALS', // ← machine code (frontend branches on this)
    status: 400,
    messages: [                                           // ← an ARRAY of i18n keys
      'ADMIN[invalid_login_credentials]',                 //   index 0 — the default message
      'ADMIN[invalid_login_credentials_locked]'           //   index 1 — pick by index at the call site
    ]
  }
};

const { ERROR_CODES, errorResponse, errorResponseRollback, joiErrorsMessage } = require('../../../services/error');

return errorResponse(req, ERROR_CODES.BAD_REQUEST_INVALID_ARGUMENTS, joiErrorsMessage(error)); // custom string (Joi)
return errorResponse(req, ERROR_CODES.ADMIN_BAD_REQUEST_ACCOUNT_INACTIVE);                       // default message
return errorResponse(req, ERROR_CODES.ADMIN_BAD_REQUEST_EMAIL_CONFLICT, 1);                      // alternate message (index 1)

// inside an open transaction, roll back first:
return errorResponseRollback(t, req, ERROR_CODES.ORDER_BAD_REQUEST_PAYMENT_FAILED);

// app/Admin/languages/en.js
module.exports = {
  'ADMIN[invalid_login_credentials]': 'The email and/or password you entered is incorrect.',
  'ADMIN[reset_email_sent]': 'An email has been sent to {{email}}.' // {{var}} interpolation
};

// inside a task — render + send through the service wrapper
const email = require('../../../services/email');

await email.send({
  to: user.email,
  template: 'booking-confirmation', // the EJS mailer
  locale: user.locale,              // mailers respect i18n, same as actions
  data: {
    name: user.firstName,
    startTime: booking.startTime
  }
});

/**
 * Exports admin data to a CSV and emails it to the requesting admin.
 *
 * @job = {
 *   @id - (INTEGER - REQUIRED): ID of the background job (Bull assigns this)
 *   @data = {
 *     @adminId - (STRING - REQUIRED): ID of the admin requesting the export
 *   }
 * }
 *
 * Success: Returns true
 */
async function V1ExportTask(job) {
  // 1. validate job.data with Joi — exactly like an action validates req.args
  const schema = joi.object({
    adminId: joi.string().uuid().required()
  });

  const { error, value } = schema.validate(job.data);

  if (error) {
    throw new Error(joiErrorsMessage(error)); // tasks THROW on failure (no errorResponse, no res)
  }

  job.data = value; // Joi has now coerced types

  try {
    // 2. do the work — anything an action can do:

    // read from the DB
    const admin = await models.admin.findByPk(job.data.adminId);

    // open a transaction for multi-step writes, exactly like an action
    const t = await models.db.transaction();
    try {
      await admin.update({ lastExportedAt: new Date() }, { transaction: t });
      await t.commit();
    } catch (err) {
      await t.rollback();
      throw err;
    }

    // enqueue ANOTHER job (tasks can create jobs too — this is the fan-out pattern)
    await AdminQueue.add('V1EmailExportReadyTask', { adminId: admin.id });

    // call an ACTION from inside the task: require it and invoke its method.
    // (actions are just functions — a task can reuse one instead of duplicating logic)
    const result = await V1GenerateReport({ args: { adminId: admin.id } });

    // ... the heavy lifting ...

    // emit a socket event so the client knows the job finished (same as actions — §10).
    // tasks have no req, so grab io via socket.getIO(); emit AFTER any commit.
    socket.getIO()
      .to(`${SOCKET_ROOMS.ADMIN}${socketWrapper(admin.id)}`)
      .emit(SOCKET_EVENTS.ADMIN_EXPORT_READY, { adminId: admin.id });

    return true; // tasks return true on success
  } catch (error) {
    throw error; // Bull marks the job failed → 'failed' handler → queueError
  }
} // END V1ExportTask

const AdminQueue = queue.get('AdminQueue');
AdminQueue.process('V1ExportTask', tasks.V1ExportTask);
AdminQueue.on('failed',  async (job, err) => queueError(err, AdminQueue, job));
AdminQueue.on('stalled', async job        => queueError(new Error('Queue Stalled.'), AdminQueue, job));
AdminQueue.on('error',   async err        => queueError(err, AdminQueue));

// another queue + task, wired the same way (one queue per feature, one process() line per task)
const UserQueue = queue.get('UserQueue');
UserQueue.process('V1CheckAllUsersTask', tasks.V1CheckAllUsersTask);
UserQueue.process('V1CheckUserTask',     tasks.V1CheckUserTask); // a queue can host many tasks
UserQueue.on('failed',  async (job, err) => queueError(err, UserQueue, job));
UserQueue.on('stalled', async job        => queueError(new Error('Queue Stalled.'), UserQueue, job));
UserQueue.on('error',   async err        => queueError(err, UserQueue));

// services/queue.js — defaultJobOptions applied to every job
{
  attempts: 5,                                   // retry transient failures
  backoff: { type: 'exponential', delay: 5000 }, // 5s → 10s → 20s → 40s between attempts
  removeOnComplete: 1000,                        // prune completed jobs (don't bloat Redis)
  removeOnFail: 5000                             // keep recent failures for inspection / replay
}

// 1. From an action (return 202 + jobId)
const job = await AdminQueue.add('V1ExportTask', {
  adminId: req.admin.id
});

return {
  status: 202,
  success: true,
  jobId: job.id
};

// 2. From a cronjob (cronjobs.js) — always UTC, enqueue only
new CronJob('0 0 * * * *', () => {
  UserQueue.add('V1CheckAllUsersTask', {});
}, null, true, 'UTC');

// 3. From another task (the fan-out pattern, below)

async function V1CheckAllUsersTask(job) {           // aggregate — no business logic
  const users = await models.user.findAll({
    where: {
      isActive: true
    },
    attributes: ['id']
  });

  for (const u of users) {
    await UserQueue.add('V1CheckUserTask', {
      userId: u.id
    });
  }

  return users.length;
} // END V1CheckAllUsersTask

// cronjobs.js
const CronJob = require('cron').CronJob;
const queue = require('./services/queue');

/***** USER *****/
const UserQueue = queue.get('UserQueue');

// Nightly cleanup of inactive users. A common trick: fire often in dev so you can
// watch it work, but use the real cadence in production.
const cleanupSchedule = NODE_ENV === 'development'
  ? '0 */5 * * * *'   // every 5 minutes in dev
  : '0 0 0 * * *';    // 00:00 UTC daily in prod

new CronJob(cleanupSchedule, () => {
  // the callback ONLY enqueues — the task does the actual work
  UserQueue.add('V1CleanupInactiveUsersTask', {});
}, null, true, 'UTC'); // start immediately, timezone UTC

// services/socket.js
socket.on(SOCKET_EVENTS.MESSAGE_CREATED, async (data, callback) => {
  try {
    const result = await V1MessageCreated(data, {
      io,
      SOCKET_ROOMS,
      SOCKET_EVENTS,
      socketWrapper
    });

    return callback(null, result);
  } catch (error) {
    // socket actions THROW; the handler returns the error via the callback
    return callback(error);
  }
});

await t.commit();

io
  .to(`${SOCKET_ROOMS.CONVERSATION}${socketWrapper(conversationId)}`)
  .emit(SOCKET_EVENTS.MESSAGE_CREATED, data);

return {
  status: 200,
  success: true,
  message
};

// ❌ BAD — logic tangled with I/O, nearly impossible to test in isolation
async function V1ProcessOrder(req) {
  const order = await models.order.findByPk(req.args.id);
  const charge = await stripeService.charge({ amount: order.amount });

  // business logic buried inside the action:
  const tax = order.amount * 0.08;
  const total = order.amount + tax;
  const status = charge.status === 'succeeded' ? 'paid' : 'failed';

  await models.order.update({ tax, total, status, chargeId: charge.id }, { where: { id: order.id } });
  return { status: 200, success: true };
}

// ✅ GOOD — pure logic extracted; each piece independently testable

// helper.js — no DB, no req: just inputs → output
function calculateOrderResult(order, charge) {
  const tax = order.amount * 0.08;
  const total = order.amount + tax;
  const status = charge.status === 'succeeded' ? 'paid' : 'failed';
  return { tax, total, status, chargeId: charge.id };
}

// V1ProcessOrder.js
async function V1ProcessOrder(req) {
  // 1. load
  const order = await models.order.findByPk(req.args.id);
  const charge = await stripeService.charge({ amount: order.amount });

  // 2. process — pure logic lives in the helper, trivial to test
  const result = calculateOrderResult(order, charge);

  // 3. save
  await models.order.update(result, { where: { id: order.id } });
  return { status: 200, success: true };
}

app/Order/tests/
├── integration/          # one file per ACTION — full HTTP via supertest, real server + DB
│   ├── V1Create.test.js
│   └── V1Query.test.js
├── tasks/                # one file per TASK — call the task fn directly, assert side effects
│   └── V1ExportTask.test.js
└── helper.test.js        # pure unit tests for the feature's helper.js — no server, no DB

/**
 * TEST ADMIN V1Login METHOD
 */

'use strict';

// load the TEST env (note: .env.test, not .env.development)
require('dotenv').config({ path: path.join(__dirname, '../../../../config/.env.test') });

// ── then the SAME import block every .js file has (§6 order: built-ins → third-party
//    → services → helpers → models → queues), e.g.: ──
const path = require('path');                                   // built-in
const request = require('supertest');                           // third-party
const _ = require('lodash');
const queue = require('../../../../services/queue');            // services
const socket = require('../../../../services/socket');
const { errorResponse, ERROR_CODES } = require('../../../../services/error');
const { adminLogin } = require('../../../../helpers/tests');     // helpers
const { reset, populate } = require('../../../../test/fixtures/sql'); // test utilities
const models = require('../../../../models');                   // models

let app = null;          // server: set in beforeAll because booting is async
let AdminQueue = null;   // declare the queue instances this file needs (assigned in beforeEach)

describe('Admin.V1Login', () => {
  // wrap the fixture require in a function so each test gets a FRESH deep copy
  // (a mutation in one test must never bleed into the next)
  const adminFixFn = () => _.cloneDeep(require('../../../../test/fixtures/fix1/admin'));
  let adminFix = null;

  // describe the route under test
  const routeVersion = '/v1';
  const routePrefix = '/admins';
  const routeMethod = '/login';
  const routeUrl = `${routeVersion}${routePrefix}${routeMethod}`;

  // boot the server ONCE for the whole file
  beforeAll(async () => {
    app = await require('../../../../server');
  });

  // before EACH test: fresh fixtures, empty queue, reset the DB
  beforeEach(async () => {
    adminFix = adminFixFn();
    AdminQueue = queue.get('AdminQueue');
    await AdminQueue.obliterate({ force: true }); // always start with an empty queue
    await socket.get();
    await reset();                                 // wipe the test database
  });

  // after ALL tests: close every connection or the process hangs
  afterAll(async () => {
    await queue.closeAll();
    await socket.close();
    await models.db.close();
    app.close();
  });

  // group test cases by the ROLE making the request
  describe('Role: Logged Out', () => {
    beforeEach(async () => {
      await populate('fix1'); // load fixture data at the narrowest scope that needs it
    });

    it('[logged-out] should login successfully', async () => {
      const res = await request(app)
        .post(routeUrl)
        .send({ email: adminFix[0].email, password: adminFix[0].password });

      expect(res.statusCode).toBe(201);
      expect(res.body.success).toBe(true);
      expect(typeof res.body.token).toBe('string');
    });

    it('[logged-out] should fail if credentials are incorrect', async () => {
      const res = await request(app)
        .post(routeUrl)
        .send({ email: 'wrong@email.com', password: 'wrongpassword' });

      expect(res.statusCode).toBe(400);
      expect(res.body).toEqual(errorResponse(i18n, ERROR_CODES.ADMIN_BAD_REQUEST_INVALID_LOGIN_CREDENTIALS));
    });
  }); // END Role: Logged Out
}); // END Admin.V1Login

it('[logged-out] should fail to login if account is inactive', async () => {
  const admin1 = adminFix[0]; // baseline: an active admin

  // mutate the baseline to the scenario you need — in the test, not in a fixture file
  await models.admin.update({ isActive: false }, { where: { id: admin1.id } });

  const res = await request(app).post(routeUrl).send({ email: admin1.email, password: admin1.password });

  expect(res.statusCode).toBe(400);
  expect(res.body).toEqual(errorResponse(i18n, ERROR_CODES.ADMIN_BAD_REQUEST_ACCOUNT_INACTIVE));
});

const { adminLogin, userLogin } = require('../../../../helpers/tests');

it('[admin] should update self successfully', async () => {
  const admin1 = adminFix[0];

  // log in first — hits the real login endpoint, returns a JWT
  const { token } = await adminLogin(app, routeVersion, request, admin1);

  const res = await request(app)
    .post(routeUrl)
    .set('authorization', `jwt-admin ${token}`) // prefix must match the type
    .send({ firstName: 'New Name' });

  expect(res.statusCode).toBe(200);
});

it('[user] should not read another user\'s private data', async () => {
  const user1 = userFix[0];
  const user2 = userFix[1];

  const { token: token1 } = await userLogin(app, routeVersion, request, user1);
  const { token: token2 } = await userLogin(app, routeVersion, request, user2);

  const res = await request(app)
    .get(routeUrl)
    .set('authorization', `jwt-user ${token1}`)
    .send({ userId: user2.id }); // user1 attempts to read user2

  expect(res.statusCode).toBe(403);
});

it('[admin] should update timezone successfully', async () => {
  const { token } = await adminLogin(app, routeVersion, request, admin1);

  const res = await request(app)
    .post(routeUrl)
    .set('authorization', `jwt-admin ${token}`)
    .send({ timezone: 'America/New_York' });

  // 1. assert the RESPONSE — status, success flag, payload shape
  expect(res.statusCode).toBe(200);
  expect(res.body.success).toBe(true);

  // 2. assert the DATABASE — never trust the response alone
  const updated = await models.admin.findByPk(admin1.id);
  expect(updated.timezone).toBe('America/New_York');
});

// 3. if the action enqueues a job, assert that too (in the integration test that triggered it)
const jobs = await AdminQueue.getJobs();
expect(jobs).toHaveLength(1);
expect(jobs[0].name).toBe('V1ExportTask');

expect(res.statusCode).toBe(400);
expect(res.body).toEqual(errorResponse(i18n, ERROR_CODES.ADMIN_BAD_REQUEST_INVALID_TIMEZONE));

// services/stripe.js is YOUR wrapper — mock the wrapper method, not the Stripe SDK
const stripeService = require('../../../../services/stripe');

describe('Order.V1Charge', () => {
  let chargeStub; // declare at describe scope so hooks can reference it

  beforeEach(async () => {
    // ... standard reset / populate ...
    chargeStub = jest.spyOn(stripeService, 'charge').mockResolvedValue({
      id: 'ch_test_123',
      status: 'succeeded',
      amount: 5000
    });
  });

  afterEach(() => {
    jest.restoreAllMocks(); // always restore after each spyOn test
  });

  it('[user] should charge successfully', async () => {
    const { token } = await userLogin(app, routeVersion, request, userFix[0]);
    const res = await request(app).post(routeUrl).set('authorization', `jwt-user ${token}`).send({ amount: 5000 });

    expect(res.statusCode).toBe(200);

    const order = await models.order.findOne({ where: { userId: userFix[0].id } });
    expect(order.stripeChargeId).toBe('ch_test_123');

    // also assert the service was CALLED correctly
    expect(chargeStub).toHaveBeenCalledTimes(1);
    expect(chargeStub).toHaveBeenCalledWith(expect.objectContaining({ amount: 5000 }));
  });

  it('[user] should handle a failed charge gracefully', async () => {
    chargeStub.mockRejectedValueOnce(new Error('Your card was declined.')); // override for THIS test only

    const { token } = await userLogin(app, routeVersion, request, userFix[0]);
    const res = await request(app).post(routeUrl).set('authorization', `jwt-user ${token}`).send({ amount: 5000 });

    expect(res.statusCode).toBe(400);
    expect(res.body).toEqual(errorResponse(i18n, ERROR_CODES.ORDER_BAD_REQUEST_PAYMENT_FAILED));
  });
});

// plain query — returns null if deletedAt is set (filtered by the default scope)
const user = await models.user.findByPk(userId);

// scope(null) — bypasses ALL default scopes, returns the raw row
const raw = await models.user.scope(null).findOne({ where: { id: userId } });
expect(raw.deletedAt).not.toBeNull(); // now you can assert the soft-delete happened

const { V1Connect } = require('../../../../app/UserSocket/actions/V1Connect');

describe('UserSocket.V1Connect', () => {
  describe('Action Only', () => {
    beforeEach(async () => {
      await populate('fix1');
    });

    it('[action-only] should connect user socket successfully', async () => {
      const user1 = userFix[0];

      // call the action directly, passing socket context explicitly
      const result = await V1Connect(
        { userId: user1.id, socketId: 'test-socket-id' },
        {
          io: socket.getIO(),
          SOCKET_ROOMS: socket.SOCKET_ROOMS,
          SOCKET_EVENTS: socket.SOCKET_EVENTS,
          socketWrapper: socket.socketWrapper
        }
      );

      // assert the return value AND the DB side effects
      expect(result).toHaveProperty('success', true);
      const userInDb = await models.user.findByPk(user1.id);
      expect(userInDb.isOnline).toBe(true);
    });
  });
});

const socket = require('../../../../services/socket');

describe('Message.V1Create', () => {
  let mockEmit, mockTo;

  beforeEach(async () => {
    await populate('fix1');

    // mock getIO so no real socket server is needed
    mockEmit = jest.fn();
    mockTo   = jest.fn(() => ({ emit: mockEmit }));
    jest.spyOn(socket, 'getIO').mockReturnValue({ to: mockTo });
  });

  afterEach(() => {
    jest.restoreAllMocks();
  });

  it('[user] should emit MESSAGE_CREATED to the conversation room', async () => {
    // ... make the HTTP request or call the action directly ...

    // assert the right ROOM was targeted
    expect(mockTo).toHaveBeenCalledWith(`CONVERSATION${socket.socketWrapper(conversationId)}`);

    // assert the right EVENT + data shape were emitted
    expect(mockEmit).toHaveBeenCalledWith(
      socket.SOCKET_EVENTS.MESSAGE_CREATED,
      expect.objectContaining({ message: expect.any(Object) })
    );
  });
});

describe('Contact.V1ExampleTask', () => {
  // ... same beforeAll / beforeEach / afterAll lifecycle ...

  it('should update the contact record after the task runs', async () => {
    // call the task directly (args come from job.data)
    await V1ExampleTask({ contactId: contactFix[0].id });

    // assert side effects — check the DB, not the queue
    const updated = await models.contact.findByPk(contactFix[0].id);
    expect(updated.processed).toBe(true);
  });
}); // END Contact.V1ExampleTask

# SCAFFOLD — A scaffolds the whole folder; B skips that and scaffolds just the new pieces
yarn gen Booking                            # A only — new feature folder (singular PascalCase)
yarn gen Booking -a V1Create                # A & B — scaffold each action
yarn gen Booking -a V1Query
yarn gen Booking -t V1SendConfirmationTask  # A & B — scaffold each task
yarn gen Booking -m Confirmation            # A & B — scaffold a mailer

# MIGRATION — A creates the table, B alters it
yarn model       # A — create-table migration
yarn migration   # B — add-columns / alter-table migration

-- Bookings: a table reservation made by a user
CREATE TABLE "Bookings" (
  id          UUID         NOT NULL DEFAULT uuid_generate_v4(), -- UUID v4 PK
  "userId"    UUID         NOT NULL,                            -- FK → Users (the owner)
  status      BOOKINGSTATUS NOT NULL DEFAULT 'PENDING',         -- ENUM type, ALL-CAPS values
  "startTime" TIMESTAMPTZ  NOT NULL,                            -- when the reservation is for (UTC)
  "partySize" INTEGER      NOT NULL DEFAULT 2,
  "isConfirmed" BOOLEAN    NOT NULL DEFAULT false,              -- boolean cols start with is/has/can/does
  notes       TEXT         NULL,
  "deletedAt" TIMESTAMPTZ  NULL,                                -- paranoid soft-delete
  "createdAt" TIMESTAMPTZ  NOT NULL,
  "updatedAt" TIMESTAMPTZ  NOT NULL,
  PRIMARY KEY (id)
);
-- index every FK
CREATE INDEX "Bookings_userId_idx" ON "Bookings" ("userId");

yarn gen Booking                          # the whole feature folder (+ adds model to sequence.js)
yarn gen Booking -a V1Create              # scaffold the create action
yarn gen Booking -a V1Query               # scaffold the list/query action
yarn gen Booking -t V1SendConfirmationTask # scaffold the background task

'use strict';

// constants used by the model (ENUM values live in a constant — see §17)
const { BOOKING_STATUSES } = require('../../helpers/constants');

// fields never exposed in any query response
const sensitiveData = [];

module.exports = (sequelize, DataTypes) => {
  const Booking = sequelize.define('booking', {
    id: {
      type: DataTypes.UUID,
      allowNull: false,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
      validate: {
        isUUID: 4
      }
    },

    // foreign keys are declared in associate(), not here

    status: {
      type: DataTypes.ENUM(...BOOKING_STATUSES),
      allowNull: false,
      defaultValue: 'PENDING'
    },

    startTime: {
      type: DataTypes.DATE,
      allowNull: false
    },

    partySize: {
      type: DataTypes.INTEGER,
      allowNull: false,
      defaultValue: 2
    },

    isConfirmed: {
      type: DataTypes.BOOLEAN,
      allowNull: false,
      defaultValue: false
    },

    notes: {
      type: DataTypes.TEXT,
      allowNull: true,
      defaultValue: null
    }
  }, {
    timestamps: true,
    paranoid: true,          // soft delete
    freezeTableName: true,
    tableName: 'Bookings',
    defaultScope: {
      attributes: {
        exclude: sensitiveData
      }
    },
    indexes: [
      { name: 'Bookings_userId_idx', fields: ['userId'] } // index every FK
    ]
  });

  // the foreign key section
  Booking.associate = models => {
    Booking.belongsTo(models.user, {
      as: 'user',
      foreignKey: {
        name: 'userId',
        allowNull: false
      },
      onDelete: 'CASCADE',
      onUpdate: 'CASCADE'
    });
  };

  Booking.getSensitiveData = () => sensitiveData;

  return Booking;
};

// migrations/<ts>-create-Booking-model.js
'use strict';

module.exports = {
  up(queryInterface, Sequelize) {
    return queryInterface.sequelize.transaction(async t => {
      await queryInterface.createTable('Bookings', {
        id: { type: Sequelize.UUID, defaultValue: Sequelize.UUIDV4, primaryKey: true, allowNull: false },
        userId: {
          type: Sequelize.UUID,
          allowNull: false,
          references: { model: 'Users', key: 'id' },
          onDelete: 'CASCADE',
          onUpdate: 'CASCADE'
        },
        status: { type: Sequelize.ENUM('PENDING', 'CONFIRMED', 'CANCELLED'), allowNull: false, defaultValue: 'PENDING' },
        startTime: { type: Sequelize.DATE, allowNull: false },
        partySize: { type: Sequelize.INTEGER, allowNull: false, defaultValue: 2 },
        isConfirmed: { type: Sequelize.BOOLEAN, allowNull: false, defaultValue: false },
        notes: { type: Sequelize.TEXT, allowNull: true, defaultValue: null },
        deletedAt: { type: Sequelize.DATE },
        createdAt: { type: Sequelize.DATE, allowNull: false },
        updatedAt: { type: Sequelize.DATE, allowNull: false }
      }, { transaction: t });

      // named index, matching the model exactly
      await queryInterface.addIndex('Bookings', ['userId'], { name: 'Bookings_userId_idx', transaction: t });
    });
  },

  down(queryInterface) {
    return queryInterface.sequelize.transaction(async t => {
      await queryInterface.dropTable('Bookings', { transaction: t });
    });
  }
};

// app/Booking/routes.js — lowercase, no separators
module.exports = (passport, router) => {
  const controller = require('./controller');

  router.all('/v1/bookings/create', controller.V1Create);
  router.all('/v1/bookings/query', controller.V1Query);

  return router;
};

// routes.js (global) — register the feature once
// app.use('/', require('./app/Booking/routes')(passport, express.Router()));

'use strict';

const { errorResponse, ERROR_CODES } = require('../../services/error');
const actions = require('./actions');

module.exports = {
  V1Create,
  V1Query
};

// pick the action by role; only a logged-in user can create a booking
async function V1Create(req, res, next) {
  let method = null;

  if (req.user) {
    method = 'V1CreateByUser';
  } else {
    return res.status(401).json(errorResponse(req, ERROR_CODES.UNAUTHORIZED));
  }

  try {
    const result = await actions[method](req, res);
    return res.status(result.status).json(result);
  } catch (error) {
    return next(error);
  }
} // END V1Create

async function V1Query(req, res, next) {
  let method = null;

  if (req.user) {
    method = 'V1QueryByUser';
  } else {
    return res.status(401).json(errorResponse(req, ERROR_CODES.UNAUTHORIZED));
  }

  try {
    const result = await actions[method](req, res);
    return res.status(result.status).json(result);
  } catch (error) {
    return next(error);
  }
} // END V1Query

// app/Booking/actions/V1Create.js
const queue = require('../../../services/queue');
const helper = require('../helper'); // feature-local pure logic (step 8)

// queues — grabbed right after models
const BookingQueue = queue.get('BookingQueue');

module.exports = {
  V1CreateByUser
};

/**
 * Create a booking
 *
 * POST /v1/bookings/create
 * Must be logged in · Roles: ['user']
 *
 * req.args = {
 *   @startTime - (STRING - REQUIRED): ISO datetime of the reservation
 *   @partySize - (NUMBER - OPTIONAL) [DEFAULT 2]
 *   @notes     - (STRING - OPTIONAL)
 * }
 * Success: 201, returns the booking
 * Errors:
 *   400: BAD_REQUEST_INVALID_ARGUMENTS
 *   400: BOOKING_BAD_REQUEST_TIME_IN_PAST
 */
async function V1CreateByUser(req, res) {
  const schema = joi.object({
    startTime: joi.date().iso().required(),
    partySize: joi.number().integer().min(1).max(20).default(2),
    notes: joi.string().trim().allow(null).optional()
  });

  const { error, value } = schema.validate(req.args);

  if (error) {
    return errorResponse(req, ERROR_CODES.BAD_REQUEST_INVALID_ARGUMENTS, joiErrorsMessage(error));
  }

  req.args = value;

  // pure business rule lives in the helper — unit-tested without a DB (step 8)
  if (!helper.isFutureBooking(req.args.startTime)) {
    return errorResponse(req, ERROR_CODES.BOOKING_BAD_REQUEST_TIME_IN_PAST);
  }

  const t = await models.db.transaction();

  try {
    const booking = await models.booking.create({
      userId: req.user.id,        // owner FK comes from the authenticated user
      startTime: req.args.startTime,
      partySize: req.args.partySize,
      notes: req.args.notes
    }, { transaction: t });

    // Path-B touch: stamp the user's most recent booking (column added to Users below).
    // Same transaction, so the booking and the stamp commit together or not at all.
    await models.user.update(
      { mostRecentBookingId: booking.id },
      { where: { id: req.user.id }, transaction: t }
    );

    await t.commit(); // commit BEFORE enqueueing

    // hand off the email to the background worker
    await BookingQueue.add('V1SendConfirmationTask', {
      bookingId: booking.id
    });

    return {
      status: 201,
      success: true,
      booking: booking.dataValues
    };
  } catch (error) {
    await t.rollback();
    throw error;
  }
} // END V1CreateByUser

// app/Booking/tasks/V1SendConfirmationTask.js
const notify = require('../../../services/notify'); // fake global service (step 8)

module.exports = {
  V1SendConfirmationTask
};

/**
 * @job.data = { @bookingId - (STRING - REQUIRED) }
 * Success: returns true
 */
async function V1SendConfirmationTask(job) {
  const schema = joi.object({
    bookingId: joi.string().uuid().required()
  });

  const { error, value } = schema.validate(job.data);

  if (error) {
    throw new Error(joiErrorsMessage(error)); // tasks throw
  }

  job.data = value;

  try {
    const booking = await models.booking.findByPk(job.data.bookingId);

    // call the (fake) notification service wrapper
    await notify.sendBookingConfirmation(booking);

    await booking.update({ isConfirmed: true });

    // tell connected clients in real time (emit after the write)
    socket.getIO()
      .to(`${SOCKET_ROOMS.USER}${socketWrapper(booking.userId)}`)
      .emit(SOCKET_EVENTS.BOOKING_CONFIRMED, { id: booking.id });

    return true;
  } catch (error) {
    throw error;
  }
} // END V1SendConfirmationTask

// app/Booking/helper.js — pure feature-local logic
'use strict';

module.exports = {
  isFutureBooking
};

// returns true if the booking time is in the future (plain in → plain out, no I/O)
function isFutureBooking(startTime) {
  return new Date(startTime).getTime() > Date.now();
} // END isFutureBooking

// services/notify.js — a GLOBAL service: our wrapper around a (fake) email/SMS provider.
// Lives in services/ because it wraps a third party and is shared infra. Tests mock THIS,
// never the underlying SDK.
'use strict';

module.exports = {
  sendBookingConfirmation
};

async function sendBookingConfirmation(booking) {
  // pretend this calls SendGrid / Twilio / etc.
  return fakeProvider.send({
    template: 'booking-confirmation',
    to: booking.userId,
    data: { startTime: booking.startTime }
  });
} // END sendBookingConfirmation

// app/Booking/tests/integration/V1Create.test.js  (lifecycle trimmed — see §12)
describe('Booking.V1Create', () => {
  describe('Role: User', () => {
    beforeEach(async () => {
      await populate('fix1');
    });

    it('[user] should create a booking and enqueue the confirmation', async () => {
      const { token } = await userLogin(app, routeVersion, request, userFix[0]);

      const res = await request(app)
        .post(routeUrl)
        .set('authorization', `jwt-user ${token}`)
        .send({ startTime: '2999-01-01T19:00:00Z', partySize: 4 });

      // 1. assert the response
      expect(res.statusCode).toBe(201);
      expect(res.body.booking).toHaveProperty('partySize', 4);

      // 2. assert the database — the booking row AND the Path-B stamp on the user
      const booking = await models.booking.findByPk(res.body.booking.id);
      expect(booking.userId).toBe(userFix[0].id);

      const user = await models.user.findByPk(userFix[0].id);
      expect(user.mostRecentBookingId).toBe(booking.id); // the Path-B column got set

      // 3. assert the job was enqueued
      const jobs = await BookingQueue.getJobs();
      expect(jobs).toHaveLength(1);
      expect(jobs[0].name).toBe('V1SendConfirmationTask');
    });

    it('[user] should reject a booking in the past', async () => {
      const { token } = await userLogin(app, routeVersion, request, userFix[0]);

      const res = await request(app)
        .post(routeUrl)
        .set('authorization', `jwt-user ${token}`)
        .send({ startTime: '2000-01-01T19:00:00Z' });

      expect(res.statusCode).toBe(400);
      expect(res.body).toEqual(errorResponse(i18n, ERROR_CODES.BOOKING_BAD_REQUEST_TIME_IN_PAST));
    });
  });

  // who-cannot: logged-out → 401
  describe('Role: Logged Out', () => {
    beforeEach(async () => { await populate('fix1'); });

    it('[logged-out] should fail to create a booking', async () => {
      const res = await request(app).post(routeUrl).send({ startTime: '2999-01-01T19:00:00Z' });
      expect(res.statusCode).toBe(401);
    });
  });
});

// app/Booking/tests/helper.test.js — pure unit test, no server/DB
const { isFutureBooking } = require('../helper');

describe('Booking helper.isFutureBooking', () => {
  it('returns true for a future time', () => {
    expect(isFutureBooking('2999-01-01T00:00:00Z')).toBe(true);
  });
  it('returns false for a past time', () => {
    expect(isFutureBooking('2000-01-01T00:00:00Z')).toBe(false);
  });
});

yarn migrate                                   # apply the create-table migration to your dev DB
npx jest app/Booking/tests --runInBand         # just this feature
yarn test                                      # the full suite (compiles i18n + fixtures first)

-- inside the existing "Users" table
  "mostRecentBookingId" UUID NULL,  -- FK → Bookings; the user's latest booking (nullable)

// app/User/model.js — inside User.associate = models => { ... }
User.belongsTo(models.booking, {
  as: 'mostRecentBooking',
  foreignKey: {
    name: 'mostRecentBookingId',
    allowNull: true              // nullable — a brand-new user has no bookings yet
  },
  onDelete: 'SET NULL',          // if that booking is deleted, just clear the pointer
  onUpdate: 'CASCADE'
});

// migrations/<ts>-add-cols-mostRecentBookingId-to-Users-tbl.js
'use strict';

module.exports = {
  up(queryInterface, Sequelize) {
    return queryInterface.sequelize.transaction(async t => {
      await queryInterface.addColumn('Users', 'mostRecentBookingId', {
        type: Sequelize.UUID,
        allowNull: true,
        references: { model: 'Bookings', key: 'id' },
        onDelete: 'SET NULL',
        onUpdate: 'CASCADE'
      }, { transaction: t });

      await queryInterface.addIndex('Users', ['mostRecentBookingId'], {
        name: 'Users_mostRecentBookingId_idx',
        transaction: t
      });
    });
  },

  down(queryInterface) {
    return queryInterface.sequelize.transaction(async t => {
      await queryInterface.removeColumn('Users', 'mostRecentBookingId', { transaction: t });
    });
  }
};

yarn gen User -a V1ReadMostRecentBooking   # scaffolds the action + its test

router.all('/v1/users/readmostrecentbooking', controller.V1ReadMostRecentBooking);

async function V1ReadMostRecentBooking(req, res, next) {
  let method = null;

  if (req.user) {
    method = 'V1ReadMostRecentBookingByUser';
  } else {
    return res.status(401).json(errorResponse(req, ERROR_CODES.UNAUTHORIZED));
  }

  try {
    const result = await actions[method](req, res);
    return res.status(result.status).json(result);
  } catch (error) {
    return next(error);
  }
} // END V1ReadMostRecentBooking

// app/User/actions/V1ReadMostRecentBooking.js
module.exports = {
  V1ReadMostRecentBookingByUser
};

/**
 * Read the logged-in user's most recent booking
 *
 * GET/POST /v1/users/readmostrecentbooking
 * Must be logged in · Roles: ['user']
 *
 * req.args = {} (none — it's always "my latest")
 * Success: 200, returns the booking
 * Errors:
 *   404: USER_NOT_FOUND_NO_RECENT_BOOKING
 */
async function V1ReadMostRecentBookingByUser(req, res) {
  try {
    // the logged-in user (req.user) already carries the pointer column
    if (!req.user.mostRecentBookingId) {
      return errorResponse(req, ERROR_CODES.USER_NOT_FOUND_NO_RECENT_BOOKING);
    }

    // fetch the booking, scoped to the owner so a user can only read their own
    const booking = await models.booking.findOne({
      where: {
        id: req.user.mostRecentBookingId,
        userId: req.user.id
      }
    });

    if (!booking) {
      return errorResponse(req, ERROR_CODES.USER_NOT_FOUND_NO_RECENT_BOOKING);
    }

    return {
      status: 200,
      success: true,
      booking: booking.dataValues
    };
  } catch (error) {
    throw error;
  }
} // END V1ReadMostRecentBookingByUser

// app/User/tests/integration/V1ReadMostRecentBooking.test.js  (lifecycle trimmed — see §12)
describe('User.V1ReadMostRecentBooking', () => {
  describe('Role: User', () => {
    beforeEach(async () => {
      await populate('fix1');
    });

    it('[user] should return the user\'s most recent booking', async () => {
      const user1 = userFix[0];
      const { token } = await userLogin(app, routeVersion, request, user1);

      // arrange: create a booking and point the user at it (mutate the baseline in-test)
      const booking = await models.booking.create({
        userId: user1.id,
        startTime: '2999-01-01T19:00:00Z',
        partySize: 2
      });
      await models.user.update({ mostRecentBookingId: booking.id }, { where: { id: user1.id } });

      const res = await request(app)
        .post(routeUrl)
        .set('authorization', `jwt-user ${token}`);

      expect(res.statusCode).toBe(200);
      expect(res.body.booking).toHaveProperty('id', booking.id);
    });

    it('[user] should 404 when the user has no recent booking', async () => {
      const { token } = await userLogin(app, routeVersion, request, userFix[0]); // baseline: no booking

      const res = await request(app)
        .post(routeUrl)
        .set('authorization', `jwt-user ${token}`);

      expect(res.statusCode).toBe(404);
      expect(res.body).toEqual(errorResponse(i18n, ERROR_CODES.USER_NOT_FOUND_NO_RECENT_BOOKING));
    });
  });

  // who-cannot: logged-out → 401
  describe('Role: Logged Out', () => {
    beforeEach(async () => { await populate('fix1'); });

    it('[logged-out] should be rejected', async () => {
      const res = await request(app).post(routeUrl);
      expect(res.statusCode).toBe(401);
    });
  });
});

yarn migrate         # run pending migrations on the dev DB
yarn mg              # alias of `yarn migrate`
yarn migrate:prod    # run pending migrations on production

yarn rollback        # undo the last migration on the dev DB
yarn rb              # alias of `yarn rollback`
yarn rollback:prod   # undo the last migration on production

yarn model           # generate a CREATE-table migration skeleton (new table), then rename
yarn migration       # generate an ALTER-table migration skeleton (add columns), then rename

yarn backup          # dump the dev DB to database/backups/backup.sql
yarn restore         # drop + recreate the dev DB from that backup (DESTRUCTIVE)
yarn seed            # load database/seed/ into the dev DB (local sample data — see below)

yarn lang           # compile languages/*.js → locales/*.json and validate keys
yarn gulp           # watch mailers/languages and regenerate preview.html / locales
yarn sql fix1       # (re)generate the test fixtures' .sql file — usually run for you by `yarn test`

yarn ngrok:auth <token>   # one-time: set your ngrok auth token
yarn ngrok                # open a public tunnel to the local server (port 8000)

yarn gen <Feature>                 # whole feature folder
yarn gen <Feature> -a V1<Action>    # add an action
yarn gen <Feature> -t V1<Action>Task # add a background task
yarn gen <Feature> -m <Mailer>      # add a mailer
yarn del <Feature> [-a|-t|-m ...]   # remove any of the above

yarn s        # web/API server (dev: nodemon + .env.development)
yarn server   # web server via the Procfile (= yarn start)

yarn w        # background worker
yarn worker   # same worker (long form)

yarn cron     # clock process — runs the cronjobs

yarn redis      # start the project-local Redis (separate terminal)
yarn redis:stop # stop the project-local Redis

yarn migrate     # run pending migrations on the dev DB
yarn mg          # alias of `yarn migrate`
yarn migrate:prod # run pending migrations on production

yarn rollback    # undo the last migration on the dev DB
yarn rb          # alias of `yarn rollback`
yarn rollback:prod # undo the last migration on production

yarn model       # generate a CREATE-table migration skeleton (new table), then rename
yarn migration   # generate an ALTER-table migration skeleton (add columns), then rename

yarn backup      # dump the dev DB to database/backups/backup.sql
yarn restore     # drop + recreate the dev DB from that backup (DESTRUCTIVE — wipes current dev data)
yarn seed        # load database/seed/ data into the dev DB (your local sample data)

yarn lang        # compile languages/*.js → locales/*.json and validate keys
yarn test        # full suite (runs `yarn lang` + `yarn sql fix1` first, then jest --runInBand)
yarn t           # alias of `yarn test`
npx jest <path> --runInBand   # run a single file / subset

yarn sql fix1    # (re)generate the test fixtures' .sql file — usually run for you by `yarn test`

yarn gulp                 # watch mailers/languages → regenerate preview.html / locales
yarn ngrok                # expose the local server publicly (for testing inbound webhooks)
yarn ngrok:auth <token>   # one-time: set your ngrok auth token

app/<Feature>/   feature folders (model, routes, controller, actions, tasks, tests, …)
middleware/      id, args, auth, error, exit
services/        email, error, language, socket, passport, queue, redis, …
helpers/         constants, cruqd, logic, schemas, session, tests
database/        index.js, schema.sql, seed/, sequence.js
migrations/      timestamped migration files
config/          .env.* (gitignored) + .env.template + config.js
locales/         compiled i18n (generated — don't edit)
redis/           project-local Redis build (gitignored)
index.js · server.js · worker.js · cronjobs.js   # the entry points
AGENTS.md · CLAUDE.md · .claude/skills/           # agent docs
README.md · docs/ · documentation.html           # human docs