TaskFlow -> Enterprise Systems

# Approval Workflow Template

## States
DRAFT -> SUBMITTED -> REVIEW -> APPROVED -> EXECUTED

## For each transition define
- command name
- allowed source state
- target state
- actor permission
- organizational scope
- monetary/other approval limits
- preconditions
- required reason/comment
- audit event
- side effects / queued work

Never expose a generic API that lets a client assign any workflow state directly.

# Audit Event Schema

Suggested fields:

- id
- occurredAt
- actorUserId / auth subject
- workspace/company/department context
- action
- entityType
- entityId
- reason
- beforeJson (only appropriate fields)
- afterJson (only appropriate fields)
- requestId / correlationId
- source (WEB/API/JOB/INTEGRATION)

For critical changes, write the audit event in the same database transaction as the business change. Do not put credentials or unnecessary sensitive data into audit payloads.

# Final Enterprise Capstone Blueprint

Choose HRIS, Procurement+Inventory, or Accounting. Produce:

1. Module/bounded-context map.
2. Key entities and invariants.
3. State/approval workflows.
4. Permission + scope + segregation-of-duties matrix.
5. Transaction boundaries.
6. Audit-event model.
7. Background-job and idempotency plan.
8. Integration contracts and outbox/inbox strategy.
9. Reporting/read-model strategy.
10. Test matrix and failure-recovery cases.
11. Deployment/observability plan.
12. ADRs for the three highest-impact architecture decisions.
13. Evidence/triggers that would justify future service extraction.

# Domain Module Catalog

| Module | Owns | Example commands |
|---|---|---|
| People | Employee/employment/org assignments | hireEmployee, transferEmployee, terminateEmployment |
| Leave | Leave balances and requests | submitLeave, approveLeave, cancelLeave |
| Payroll | Payroll runs/pay items/deductions | calculatePayroll, finalizePayroll, markPaid |
| Procurement | Requisitions/POs/suppliers | submitRequisition, approvePO, cancelPO |
| Inventory | Items/warehouses/movements | receiveStock, issueStock, transferStock |
| Accounting | Accounts/journals/periods | postJournal, closePeriod, reverseJournal |
| Recruitment | Openings/applicants/offers | advanceApplicant, approveOffer, hireApplicant |

Each module exports a small public service/event contract. Do not expose repositories or Prisma models as the default cross-module API.

# Enterprise Architecture Map

```text
Next.js
  -> NestJS/Fastify modular application
      -> People / Payroll / Leave / Procurement / Inventory / Accounting / Recruitment
      -> Repository interfaces / Prisma implementations
      -> PostgreSQL
      -> BullMQ workers for long-running work
      -> Supabase Auth / Storage / Realtime where applicable
```

Start as a modular monolith. Extract workers or services only when scaling, reliability, compliance, release cadence, or team ownership creates real pressure.

# Enterprise Permission Matrix - Example

| Role | Scope | Example permissions | Extra constraints |
|---|---|---|---|
| HR Officer | company/department | employee.read, leave.review | cannot edit payroll result |
| Payroll Officer | company | payroll.calculate, payslip.generate | finalization may require second approver |
| Supervisor | team | leave.approve, employee.read.team | relationship-scoped |
| Procurement Officer | business unit | requisition.manage, po.create | cannot final approve own PO |
| Department Head | department | po.approve | approval amount threshold |
| Accounting | company | journal.post, period.read | closed-period rule |

Authorization decision = identity + scope + permission + relationship + business rule.

# Financial Correctness Checklist

- Use exact decimal/numeric amounts, never binary float for authoritative money.
- Store currency explicitly.
- Define rounding mode and rounding stage.
- Version tables/formulas/rates used for payroll calculations.
- Finalized payroll/journals should be immutable; corrections use adjustments/reversals.
- Journal entries must balance before posting.
- Closed accounting periods reject normal postings.
- Recalculation must be reproducible from durable inputs/version references.

# Idempotency and Background Jobs

Course line:
- @nestjs/bullmq 12.0.0
- BullMQ 6.x

## Example job key
`payroll-run:<runId>:calculate`

## Worker rule
1. Load durable operation state.
2. If already completed, return the durable result.
3. Claim/process according to concurrency policy.
4. Persist progress/results.
5. Make external side effects independently idempotent.

BullMQ recommends idempotent jobs so retries converge to the same final state. BullMQ 6 uses Job Schedulers for recurring work.

# Integration Boundaries

## Outbound
Business transaction -> outbox row -> worker -> external provider -> delivery state.

## Inbound webhook
Verify authenticity -> persist provider event ID -> deduplicate -> process business command -> persist result.

## Contract rule
Use business events such as `PurchaseOrderApproved` and version their payloads. Avoid publishing raw Prisma rows as long-lived external contracts.

# Migration Roadmap

## Stage 1 - Modular monolith
Single API, explicit Nest feature modules, one PostgreSQL cluster.

## Stage 2 - Worker separation
BullMQ workers for payroll calculation, imports, exports, notification batches, integrations.

## Stage 3 - Read scaling
Indexes, read models, replicas/analytics pipeline where evidence requires.

## Stage 4 - Selective service extraction
Only modules with independent scale/reliability/team/compliance pressure.

## Infrastructure replacement path
- Supabase PostgreSQL -> self-hosted/AWS PostgreSQL
- Supabase Storage -> S3-compatible storage adapter
- Upstash/managed Redis -> alternate Redis
- Railway/Render -> AWS containers/Kubernetes when operations justify it

# TaskFlow Enterprise Systems Blueprint

This is the final course reference snapshot. It does not turn TaskFlow into one giant ERP implementation. Instead it provides reusable architecture templates for evolving the same principles into HRIS, payroll, procurement, inventory, accounting, recruitment, and other enterprise modules.

The default evolution strategy is:
1. modular monolith,
2. durable background workers,
3. purpose-built read models,
4. selective service extraction only when evidence justifies it.

# Reporting Architecture

Start simple:
1. Indexed PostgreSQL query.
2. Purpose-built projection/select.
3. View/materialized read model if repeated pressure justifies it.
4. Background job for large Excel/PDF exports.
5. Store generated artifact metadata; Storage holds bytes.

Always apply tenant/department authorization to reports and exports. Historical reports must use effective-dated/versioned business data where required.

# Phase 36 Sources

Official references consulted:

- NestJS Modules: https://docs.nestjs.com/modules
- BullMQ Idempotent Jobs: https://docs.bullmq.io/patterns/idempotent-jobs
- BullMQ Job IDs/Deduplication: https://docs.bullmq.io/guide/jobs/job-ids
- BullMQ Job Schedulers: https://docs.bullmq.io/guide/job-schedulers/
- BullMQ Flows: https://docs.bullmq.io/guide/flows/
- @nestjs/bullmq npm: https://www.npmjs.com/package/@nestjs/bullmq
- BullMQ npm: https://www.npmjs.com/package/bullmq
- PostgreSQL 18 Monetary Types: https://www.postgresql.org/docs/18/datatype-money.html
- PostgreSQL 18 Data Types (`numeric` / `decimal` exact numeric): https://www.postgresql.org/docs/18/datatype.html

Architecture patterns such as modular monoliths, transactional outbox/inbox, effective-dated history, segregation of duties, and read models are presented as engineering patterns; their exact implementation must follow the target organization's regulatory and business requirements.

# Phase 36 Version Notes

Existing course locks remain:
- Next.js 16.x
- NestJS 12.x
- Fastify 5.x
- Prisma 7.9.1 (hard course lock)
- PostgreSQL 18 line
- Zod 4.x
- TanStack Query 5.x

New enterprise-worker line verified for this phase:
- @nestjs/bullmq 12.0.0
- BullMQ 6.x (current npm line observed: 6.3.x)

Do not auto-upgrade these inside an existing course checkpoint. Verify release notes and tests first.

export type PayrollRunState =
  | "DRAFT"
  | "CALCULATING"
  | "REVIEW"
  | "FINALIZED"
  | "PAID";

// FINALIZED results should normally become immutable.
// Corrections should create explicit adjustments/reversals rather than
// silently rewriting historical payroll evidence.

export type PurchaseOrderState =
  | "DRAFT"
  | "SUBMITTED"
  | "APPROVED"
  | "REJECTED"
  | "CANCELED";

export function canApprovePurchaseOrder(
  state: PurchaseOrderState,
): boolean {
  return state === "SUBMITTED";
}

// Real policy additionally checks permission, scope, approval limit,
// segregation of duties, budget, and other organization rules.

import { Module } from "@nestjs/common";

// Illustrative final-course module boundary.
@Module({
  imports: [],
  controllers: [],
  providers: [],
  exports: [],
})
export class ProcurementModule {}

// Pseudocode-level example for Phase 36.

async function calculatePayrollJob(runId: string) {
  const run = await loadPayrollRun(runId);

  if (run.status === "FINALIZED" || run.status === "CALCULATED") {
    return run; // durable idempotent result
  }

  await claimRunForCalculation(runId);
  const result = await calculateFromVersionedInputs(runId);
  return persistCalculatedResult(runId, result);
}

declare function loadPayrollRun(id: string): Promise<any>;
declare function claimRunForCalculation(id: string): Promise<void>;
declare function calculateFromVersionedInputs(id: string): Promise<any>;
declare function persistCalculatedResult(id: string, value: any): Promise<any>;

# Enterprise Test Matrix

| Risk | Minimum verification |
|---|---|
| Unauthorized payroll finalization | HTTP E2E + permission policy test |
| Duplicate payroll job delivery | idempotency integration test |
| PO creator self-approves despite SoD | authorization/business policy test |
| Stock transfer partially commits | PostgreSQL transaction/failure integration test |
| Accounting journal unbalanced | pure policy + service test |
| Closed-period posting | service + HTTP E2E |
| Webhook delivered twice | inbox/idempotency integration test |
| Outbox publish fails after DB commit | worker recovery test |
| Report leaks another department | real PostgreSQL scoped query + E2E |
| Audit record missing on critical command | transaction integration test |
| Finalized payroll mutated | repository/service invariant test |
| Worker retry exposes duplicate external side effect | integration contract/idempotency test |