Skip to main content

User Journeys BDD

Global Rules & Conventions​

Statuses & State Model

  • Document status (canonical): draft → in_approval → released → effective.
    • Aliases: under_review ≡ in_approval; approved_pending_training is represented as released with Training Gate = ON until effective criteria are met.
    • Terminal/secondary states: superseded (archived previous version), obsolete (retired; no longer in use).
    • Workflow System: Documents using workflow templates follow workflow-defined states and transitions. The workflow system supports custom states with state-based approval rules. Status changes occur when documents transition between workflow states.
  • Deviation status (canonical): open → in_review → actions_in_progress → awaiting_effectiveness_check → resolved/closed → approved (QA approval marks final state approved).
  • CAPA status (canonical): draft → open → planned → in_progress → completed → effectiveness_verified → closed.
    • Draft Status: CAPAs without linked documents start as "draft" and require QA/Admin approval before transitioning to "open".

Numbering & Versioning

  • Auto-numbering: Documents (e.g., SOP-1, SOP-2…), Deviations, and CAPA have system-generated identifiers.
  • Versioning: New upload creates a new immutable version; prior version becomes superseded (read-only, visible in audit trail).
  • No inline editing: Files cannot be edited online; collaborators download, edit offline, and re-upload a new revision.

RBAC & Admin Customization

  • RBAC is granular to actions (create/upload, configure approval, approve, sign, train, audit, classify, close, customize dropdowns, etc.). Roles are customizable by admins.
  • Dynamic dropdowns: Each dropdown shows Default Options first, then a separator and a ⚙️ Customize Options control (admin-only) to manage values.
  • AI assistance: System may provide AI recommendations (e.g., deviation classification). QA has final authority; AI never auto-commits decisions.

Audit & Signatures

  • Audit log is immutable and records: timestamp, actor, action, entity, version, and context.
  • Electronic signatures capture: signer, meaning/intent, date-time, and are bound to the signed record and audit log.

Training Gate

  • If Training Required = ON, document remains released (gated) and becomes effective only when either:
    • N days have elapsed since release (author/ISO-configured), or
    • Training completion ≥ N% (policy-configured).

Notifications

  • When explicitly stated, system delivers notifications (web + email) to relevant users.

Feature: Document Lifecycle​

Background​

Given I am authenticated under RBAC

And audit logging is enabled for all actions

And document identifiers and versions are auto-generated

Scenario: Upload a new document​

Given I have permission to create documents

When I upload a document titled “Quality Manual” with file “manual.pdf”

And I select a document type (e.g., "Standard Operating Procedure")

And I select a workflow template (or use the default template for the document type)

Then the document is created with status “draft”

And a workflow instance is initialized with the selected template

And the document's current workflow state is set to the template's initial state

And collaborators (editors or QA managers) can be assigned for review

And collaborators can download and re-upload edited revisions (no online editing)

And an audit log entry is recorded for creation

And the document can be previewed in-app (PDF, DOCX)

V2 Design Note: The Document Upload Wizard and Document Workspace in docs/frontend/document_lifecycle_flow.md provide enhanced features like smart metadata extraction, AI suggestions, drag-and-drop upload, and in-app preview with zoom/pan controls, reducing clicks by 50% and completion time by 50% for document uploads.

Workflow System Note: The system now supports configurable workflow templates with document type-based defaults. Admins can create custom workflow templates with states, transitions, and approval rules. Documents using workflow templates follow state-based approval processes with automatic transitions when approval requirements are met.

Scenario: Collaborate with comments (offline edits)​

Given a document is in “draft”

And collaborators are assigned

When collaborators re-upload their edited files with comments

Then their comments are visible in the collaboration thread

And the latest uploaded revision is tracked under the draft version

And an audit entry records each collaborator upload and comment

V2 Design Note on Draft Collaboration Comments: The v2 design in docs/frontend/document_lifecycle_flow.md primarily details "Comment Threads" within the Approval Workflow. For draft documents with offline edits, comments are expected to be included during the re-upload process (e.g., via a dedicated comment field in the Upload Wizard or a similar mechanism), and these comments would be visible in the Version Management timeline and Audit Trail Explorer. A distinct "collaboration thread" specifically for pre-approval draft comments beyond version history is not explicitly outlined, and further clarification on its dedicated UI/UX is recommended if a separate thread is desired.

Scenario: Configure and start approval​

Given a draft document with workflow template assigned

And the workflow template defines approval rules (role-based or user-specific)

When I start the approval process (or the workflow auto-transitions based on configuration)

Then the document status may change to “in_approval” (or workflow-defined state)

And the document's current workflow state transitions to the approval state

And required signers (per workflow state approval rules) are notified

And the workflow system tracks approvals for the current state

V2 Design Note: The Approval Workflow in docs/frontend/document_lifecycle_flow.md features parallel approvals, real-time signature tracking, comment threads per approval step, and deadline alerts. This streamlines the process, contributing to a 50% reduction in clicks and completion time for approvals.

Workflow System Note: The configurable workflow system allows admins to define workflow templates with custom states and transitions. Each state can have role-based or user-specific approval requirements. When all approvals for a state are collected, the document automatically transitions to the next workflow state.

Scenario: Approve a document with required signatures​

Given I am a QA user with approval permissions

And the document is using a workflow template

And the document is in a workflow state that requires my approval (based on role or user assignment)

And I am a required signer per the workflow state's approval rules

When I approve the document with intent “I approve this document”

Then my approval is recorded in the workflow system for the current state

And my electronic signature is captured immutably with date-time

And the workflow system checks if all required approvals for the current state are collected

And when all required approvals are collected the document automatically transitions to the next workflow state

And if the next state is terminal (e.g., "released"), the document status changes accordingly

And the document metadata includes version, release date, and signer information

And workflow history records the state transition

V2 Design Note: The Signature Management Center and Signature Portal described in docs/frontend/audit_signatures_flow.md ensure GMP-compliant electronic signatures with biometric, digital, or PIN authentication, integrated seamlessly into the document approval workflow. This is part of the overall 50% faster audit processes and streamlined signature workflows.

Workflow System Note: Workflow-based documents use state-based approvals where each workflow state can have different approval requirements. The system automatically transitions documents to the next state when all approvals for the current state are collected. Legacy documents (without workflow templates) use the traditional approval system.

Scenario: Release with training gate ON​

Given the document is “released” and Training Required = ON

And training groups have been assigned

When training is scheduled to all group members

Then the system tracks completion rates

And the document becomes “effective” when (N days elapsed) or (completion ≥ N%) is satisfied

V2 Design Note: The Training Gate Dashboard and Training Analytics Dashboard in docs/frontend/document_lifecycle_flow.md and docs/frontend/training_flow.md respectively, provide interactive progress visualization, assignment tracking, and threshold alerts, ensuring automated transitions to "effective" status and contributing to 35% faster training completion.

Scenario: Release with no training required​

Given the document is “released” and Training Required = OFF

When the release is confirmed

Then the document status immediately becomes “effective”

V2 Design Note: This scenario benefits from the overall Document Workspace and its Status Timeline in docs/frontend/document_lifecycle_flow.md, ensuring clear state indicators and immediate feedback upon release confirmation, contributing to the 40% faster document lifecycle management.

Scenario: Create a new version​

Given I have permission to update documents

And there is an “effective” document

When I upload a new version with description “Updated procedures”

Then a new version is created in “draft”

And the previous version becomes superseded (archived) but remains visible for audit trail

And an audit log records the version change

V2 Design Note: The Version Management in docs/frontend/document_lifecycle_flow.md offers advanced features like side-by-side comparison with diff highlighting, a chronological version timeline, and one-click restoration, making version management 55% faster.

Scenario: Mark document obsolete​

Given a document is no longer a valid SOP

When a QA manager retires the document

Then the status changes to “obsolete”

And the document is removed from active training assignments

And the audit trail records the retirement and reason

Scenario: Assign auditors to a document​

Given I am an admin

And a document requires audit

When I allocate auditors to the document

Then auditors receive notifications

And the assignment is recorded in the audit log

Feature: Deviation Management & CAPA​

Background​

Given deviation numbers and CAPA numbers are auto-generated

And dynamic dropdowns are available with admin customization

And AI can suggest a classification but QA makes the final selection

Scenario: Report a deviation (core)​

Given I am logged in

And a deviation form template is available (default template or selected template)

When I submit a deviation using the dynamic form builder

And I fill out form sections:

  • Basic Information: Title (text), Description (textarea), Severity (select with AI suggestion enabled)
  • Additional Details: Product Name, Lot Number, Batch Number, Impact Assessment (textarea), Customer Impact (select)
  • Related Items: Related Documents (document_picker - multi-select), Related CAPAs (capa_picker - multi-select)
  • Attachments: Images (image upload with drag-and-drop), Supporting Documents (file upload)

And AI analyzes the description and suggests severity with confidence score

Then a deviation is created with status “open”

And the deviation's form_template_id is set to the selected template

And DeviationFormData record is created with all form data stored as JSON

And related documents are linked via DeviationDocument many-to-many associations

And attachments are linked via attachment_ids array

And AI classification data is stored (ai_severity_suggestion, ai_classification_confidence, ai_classification_rationale)

And relevant users are notified

And an audit log entry is recorded

V2 Design Note: The Deviation Report Wizard in docs/frontend/deviations_capa_flow.md offers smart categorization, AI classification, photo upload, and draft saving capabilities. This streamlines reporting, resulting in a 50% reduction in clicks and a 50% faster completion time.

Form Builder Note: The system now supports dynamic, configurable deviation forms with templates, sections, and fields. Admins can create form templates with custom sections and field types (text, textarea, select, document_picker, capa_picker, image, file). The default template includes 4 sections covering all standard deviation reporting needs.

Scenario: QA classification with AI recommendation​

Given a deviation is in “in_review”

And the system proposes a classification (minor/medium/major)

When QA reviews the recommendation and selects a value in the dropdown

Then the QA-selected value is stored as the official classification

And the AI suggestion and rationale are recorded for traceability

V2 Design Note: The AI Classification Assistant within the Deviation Workspace (docs/frontend/deviations_capa_flow.md) provides AI-powered classification with confidence scores and allows QA override, ensuring human judgment is preserved with an audit trail. This integration makes the process more efficient and transparent.

Scenario: Create CAPA from deviation​

Given there is an open deviation requiring systemic action

When a QA user creates a CAPA with root cause analysis

And the CAPA has no linked document_id

Then the CAPA is created with status "draft"

And the CAPA is linked to the deviation(s) via DeviationCAPA many-to-many associations

And the CAPA requires QA Manager or Admin approval before activation

When a QA Manager or Admin approves the draft CAPA

Then the CAPA status transitions from "draft" to "open"

And default CAPA action is auto-created (if none exist)

And CAPA actions are assignable to owners with due dates

And the CAPA record includes required fields:

  • Source/Trigger, Linked Records, Initiator, Date Initiated
  • Problem Description, Background/References, Impacted Product/Batch/Process
  • Root Cause (Method, Category, Detailed Statement)
  • Corrective & Preventive Action Plans (Owners, Due Dates, Verification of Completion)
  • Risk Assessment (Initial, Residual, Acceptability, Justification)
  • Effectiveness Check (Planned Date, Criteria, Result, Next Steps)
  • Review & Approval (QA Review, QA Closure with signatures)
  • Attachments

CAPA Draft Approval Note: CAPAs without linked documents start as "draft" status and require QA/Admin approval before they can be activated. This ensures proper review of standalone CAPAs before action assignment begins. Draft CAPAs appear in the pending approvals dashboard for QA Managers and Admins.

V2 Design Note: The CAPA Creation Wizard in docs/frontend/deviations_capa_flow.md includes visual tools for action planning, AI-suggested owners, an interactive risk matrix, and a template library, reducing clicks by 53% and completion time by 54% for CAPA creation.

Scenario: Complete a CAPA action with effectiveness check​

Given I am assigned to a CAPA action in “in_progress”

When I complete the action and submit evidence

Then the action status becomes “completed”

And an electronic signature is recorded with action details and timestamp

And the CAPA status updates automatically when all actions are completed

And an effectiveness check task is scheduled near the deadline

V2 Design Note: The CAPA Workspace (Action Board) and Effectiveness Review Portal in docs/frontend/deviations_capa_flow.md provide a Kanban board for visual action tracking, progress metrics, evidence galleries, and a structured review process. This leads to a 50% reduction in clicks and a 58% faster effectiveness review.

Scenario: Approve deviation resolution​

Given a deviation has a proposed resolution with linked CAPA (if any)

When a QA user approves the resolution with signature

Then the deviation status changes to “approved”

And the signature and approval details are logged

Scenario Outline: Branch A — Minor deviation, no CAPA required​

Given a deviation is categorized as

And QA determines CAPA is not required

When immediate corrections and documentation are verified

Then the deviation is closed without CAPA

And an approval signature is captured

Examples:

| severity |

| minor    |

Scenario: Branch B — Invalid/duplicate deviation rejected​

Given a submitted deviation is invalid or duplicate

When QA documents the rejection reason

Then the deviation is rejected

And the reporter is notified with explanation

And the audit trail records the rejection

Scenario: Branch C — High-priority deviation escalated​

Given a critical deviation is reported

When emergency protocols are activated and stakeholders/regulators are notified

Then rapid containment, parallel investigation, and accelerated CAPA are initiated

And daily progress tracking is enabled until closure

Scenario: Recurrence detection using RAG​

Given historical deviations and CAPA records exist

When the system performs a RAG-based similarity search on a new deviation

Then likely recurrences are shown to QA

And links to prior records are provided for faster root cause and action planning

Feature: Training​

Background​

Given training can be assigned to groups and users

And admins can toggle Comments on training sessions

And training is presented as a slideshow; each page advances a progress bar

And optional e-learning quiz may be required for completion

Scenario: Assign training to a group​

Given I am an admin and there is a released document with Training Required = ON

When I assign training to a group

Then training records are created for each user with deadlines

And users receive notifications

V2 Design Note: The Training Assignment Wizard in docs/frontend/training_flow.md streamlines this process with multi-select group assignment, smart suggestions based on document access, calendar integration for deadlines, and bulk notification options, reducing clicks by 45% and assignment time by 38%.

Scenario: Complete training with quiz and signature​

Given I am a user with a pending training

And the training includes a quiz

When I view all slides, complete the quiz, and sign electronically

Then my training record is marked completed with timestamp

And the signature is linked to the training record

V2 Design Note: The Training Detail Page in docs/frontend/training_flow.md features an interactive slideshow, quiz integration with immediate feedback, bookmarking, and certificate generation. This enhances the user experience and contributes to a 50% reduction in clicks and a 38% faster training completion process.

Scenario: Training progress & overdue tracking​

Given I am an admin

When I view training statistics for a document

Then I see completion percentages by group and overall

And overdue trainings are highlighted

V2 Design Note: The Training Analytics Dashboard in docs/frontend/training_flow.md provides interactive charts for completion rates, overdue tracking with priority highlighting, and trend analysis, enabling admins to efficiently monitor training progress and contributing to a 60% faster progress check.

Scenario: Comments on/off​

Given Admin has Comments = ON for training

When users leave comments on a training

Then comments appear in the training thread with timestamps

And if Comments = OFF, the comment UI is hidden for users

V2 Design Note: The Training Detail Page in docs/frontend/training_flow.md explicitly features a "Comments System (when enabled)" with a rich text editor and @mentions, fully supporting this scenario. The "when enabled" refers to the Admin's configuration.

Scenario: Document becomes effective after training threshold​

Given a released document with Training Required = ON and threshold N%

When the system detects completion ≥ N% (or N days elapsed)

Then the document transitions to “effective”

And the transition is recorded in audit log

Feature: Audit​

Scenario: View audit trail of a document​

Given I am an auditor

And the document has activity

When I view the audit trail

Then I see all actions with timestamp, user, action details, version, and signatures

V2 Design Note: The Audit Trail Explorer in docs/frontend/audit_signatures_flow.md offers multi-dimensional filtering, timeline visualization, and semantic search, enhancing the review process and contributing to a 75% faster audit trail review.

Scenario: Create an audit finding​

Given I am allocated to audit a document

When I record a finding with severity “major” and a description

Then the finding is saved with status “open”

And the document owner is notified

V2 Design Note: The Audit Finding Wizard in docs/frontend/audit_signatures_flow.md provides a step-by-step process for creating findings, including smart evidence upload, AI-assisted classification, and collaborative drafting, reducing clicks by 58% and creation time by 50%.

Scenario: Resolve an audit finding​

Given there is an open finding

When a QA user resolves the finding

Then the status changes to “resolved”

And the resolution timestamp is stored

V2 Design Note: The Audit Finding Workspace in docs/frontend/audit_signatures_flow.md provides interactive features such as a status timeline, evidence gallery, CAPA integration, and progress dashboards for efficient resolution, contributing to the overall 50% faster audit processes.

Scenario: End-to-end audit workflow (golden path)​

Given an audit is planned with scope, objectives, and schedule

When auditors execute the plan (document review, observations, interviews, evidence collection)

Then findings are documented with root cause analyses and CAPA recommendations

And a final report is issued and follow-up verification is scheduled

V2 Design Note: The Compliance Hub and Audit Report Generator in docs/frontend/audit_signatures_flow.md support comprehensive audit planning, execution, and reporting. AI integration assists with anomaly detection and risk assessment, making the end-to-end audit workflow significantly more efficient.

Feature: Electronic Signatures​

Background​

Given the platform enforces identity verification, signature meaning acknowledgment, and secure timestamping

Scenario: Sign document approval​

Given I am a required signer for a document pending my signature

When I sign with intent “I approve this document”

Then the signature is recorded immutably and the workflow progresses

And an audit log entry is created

V2 Design Note: The Signature Management Center and Signature Portal in docs/frontend/audit_signatures_flow.md provide GMP-compliant electronic signatures with robust identity verification, meaning acknowledgment, and secure timestamping. This is part of the overall 60% fewer clicks and 50% faster audit and signature processes.

Scenario: Sign training completion​

Given I am completing an assigned training

When I provide my electronic signature

Then the training is marked as completed with timestamp and signer identity

Scenario: Sign CAPA action completion​

Given I am assigned to a CAPA action

When I complete the action and sign off

Then the action is marked completed and the signature is recorded with action details

Scenario: Batch signatures​

Given multiple related items require signature

When I authenticate once and sign the batch with meaning acknowledgment

Then each item records an individual timestamp and audit entry

V2 Design Note: The Batch Signature Studio in docs/frontend/audit_signatures_flow.md enables efficient batch processing, allowing users to authenticate once and apply signatures to multiple documents with progress tracking and error handling, further reducing clicks and speeding up signature processing.

Scenario: Signature rejection​

Given I receive a signature request

When I decline and provide a reason

Then the system records the rejection and notifies the appropriate personnel

Scenario: Witnessed signature​

Given a critical signature requires a witness

When the primary signer and witness both authenticate and sign

Then dual signatures and timestamps are recorded with witness qualification verification

Admin & UI Validation Scenarios​

Scenario: Dynamic dropdown customization​

Given I am an admin viewing a dropdown with defaults

When I click ⚙️ Customize Options

Then I can add/edit/remove options

And the updated options are immediately available to users

And all changes are audit-logged

Scenario Outline: RBAC enforcement on actions​

Given a user with role

When they attempt action

Then the system

Examples:

| role          | action                      | result              |

| Author        | start_approval              | permitted           |

| Author        | approve_document            | forbidden           |

| QA            | approve_document            | permitted           |

| Auditor       | create_deviation            | permitted           |

| Auditor       | close_CAPA                  | forbidden           |

| Admin         | customize_dropdown_options  | permitted           |

Scenario: Document preview support​

Given I open a document in the UI

When the file is PDF or DOCX

Then the system renders an in-app preview

And shows download + re-upload controls for revisions

Scenario: Auto-numbering format​

Given I create a new SOP

When the record is saved

Then the system assigns the next number in sequence (e.g., SOP-23)

And the format is consistent across lists and audit logs

Data Quality & Compliance Scenarios​

Scenario: Mandatory fields validation (Deviations & CAPA)​

Given I submit a Deviation or CAPA

When required fields are missing

Then the system blocks submission and lists missing fields

Scenario: Immutable audit trail​

Given an audit log entry exists

When any user attempts to modify or delete it

Then the system prevents the change and records the attempt

Scenario: Timezone & timestamp consistency​

Given the system records timestamps

When actions occur across regions

Then all audit entries store UTC with local display per user settings

Non-Functional Acceptance (selected)​

  • Security: RBAC, least privilege, tamper-evident logs, e-sign per 21 CFR Part 11 / Annex 11 principles (intent, identity, timestamp).
  • Usability: Clear state indicators; preview for PDF/DOCX; progress bars for training.
  • Reliability: All state transitions are atomic and logged.
  • Interoperability: Linked records between Deviations, CAPA, Training, and Documents.

End of Unified BDD