Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lerichardv/patolab-platform/llms.txt

Use this file to discover all available pages before exploring further.

The Specimen module is the operational core of PatoLab. Every diagnostic case begins here: when a specimen is received, it is registered alongside its patient, specimen type, examination, referrer, and billing information, and it immediately enters a prioritised Kanban board where laboratory staff can track it through every phase of the diagnostic process. All subsequent workflows — report editing, invoicing, commissions, and patient notifications — are anchored to a specimen record.

​
Workflow Statuses

Each specimen carries a status field that advances through seven defined stages. The platform maps each status to a distinct colour so staff can identify a specimen’s phase at a glance on the Kanban board.
StatusHex ColourTailwind AliasDescription
received#3b82f6blue-500Specimen has arrived at the lab and been registered.
macroscopic_review#8b5cf6violet-500Pathologist is performing gross (macroscopic) examination.
processing#f59e0bamber-500Tissue is being processed (fixation, embedding, sectioning).
microscopic_review#d946effuchsia-500Pathologist is examining slides under the microscope.
finalized#10b981emerald-500Report has been signed off and the PDF has been generated.
delivered#64748bslate-500Report has been delivered to the patient.
cancelled#ef4444red-500Specimen has been voided and removed from active views.
The computed status_color attribute is automatically appended to every Specimen response, so the React frontend never needs to map status to colour independently.

​
Kanban Board

Specimens on the index page (GET /specimens) are organised into priority lanes — one swimlane per configured Priority record. Within each lane, cards are sorted by an explicit board_order integer stored in the priorities_specimens_order table, so drag-and-drop reordering is fully server-persisted. When a card is moved to a different lane or reordered within a lane, the frontend sends a batch update: 
POST /specimens/update-order

{
  "items": [
    { "id": 42, "priority_id": 2, "order": 1 },
    { "id": 17, "priority_id": 2, "order": 2 }
  ]
}
Moving a card to a different priority lane also updates the specimen’s priority_id field automatically.

​
Key Operations

Specimens are created via the Kanban board’s creation modal. The request is submitted to:
POST /specimens
Specimen fields (stored in the specimen table):
FieldTypeRequiredNotes
customerinteger (FK)✅References customers.id
specimen_typeinteger (FK)✅References specimen_type.id
specimen_type_examinationinteger (FK)✅References specimen_type_examination.id
specimen_categoryinteger (FK)✅References specimen_category.id
referrerinteger (FK)✅References referrers.id
priority_idinteger (FK)✅References priorities.id
statusstring✅Initial status (typically received)
anatomic_sitestring❌Location of the tissue biopsy
diagnosisstring❌Preliminary clinical diagnosis
clinical_notesstring❌Free-text clinical context
medical_order_filefile❌PDF or image (max 30 MB PDF / 10 MB image)
Invoice billing fields (passed in the same request but stored in the invoices table):
FieldTypeRequiredNotes
quantityinteger✅Invoice line quantity (min: 1)
amountnumeric✅Gross invoice amount
discountnumeric✅Discount amount
payment_typestring✅cash, credit card, bank transfer, check, or credit
age_discount_typestring❌third or fourth age discount
age_discount_amountnumeric❌Age-based discount amount
custom_amountnumeric❌Override charge separate from the base price
custom_amount_reasonstring❌Explanation for the custom amount
Creating a specimen also generates an invoice, consumes a CAI sequence number, deducts any linked insumos (supply products) from inventory, and sends a WhatsApp notification to the patient.
Each specimen may have one or more pathologists assigned to it. Access can be scoped independently to the macroscopy and microscopy phases.Assign a pathologist:
POST /specimens/{specimen}/assign-user

{
  "user_id": 5,
  "macroscopy_access": true,
  "microscopy_access": false
}
If the user is already assigned, the pivot record is updated in place (no duplicate).Remove a pathologist:
POST /specimens/{specimen}/unassign-user

{
  "user_id": 5
}
Pathologist access flags (macroscopy_access, microscopy_access) control which editor sections the user can write to inside the report editor.
Select multiple specimens on the Kanban board to apply an action to all of them at once:
POST /specimens/bulk-action

{
  "ids": [12, 15, 23],
  "action": "change_status",
  "value": "processing"
}
Supported action values:
ActionvalueRequired permission
change_statusNew status stringspecimens.edit
change_priorityPriority IDspecimens.edit
assign_pathologistUser IDspecimens.manage
unassign_pathologistUser IDspecimens.manage
delete(not used)specimens.delete
Deleting via bulk action performs a soft delete by setting active = false; the record is not removed from the database.
Multiple specimens belonging to the same patient visit can be bundled into a specimen group for collective invoicing and public tracking:
POST /specimen-groups
A group has its own combined invoice and its own public progress page (see Public Tracking URLs below).

​
Public Tracking URLs

PatoLab generates two unauthenticated, token-protected pages that patients can access without logging in.

​
Individual Specimen Progress

GET /specimen/{specimen_code}?token={access_token}
Displays the specimen’s current status, type, and examination in a patient-friendly view. When the specimen transitions to finalized, a delivery_token is embedded in the WhatsApp notification link. Visiting the page with the correct delivery_token automatically advances the status to delivered.

​
Specimen Group Progress

GET /specimen-group/{id}
Shows the aggregate progress of all specimens in a group, useful for patients who had multiple analyses in one visit.
The Specimen model has two grouping flags: is_group (boolean, cast) marks specimens that are part of a group billing scenario, and group_id (FK to specimen_groups) links the individual specimen to its parent group. Check both fields when building invoicing or reporting logic that must account for grouped cases.

​
Filters

The Kanban index view supports four concurrent filters: status (multi-select), specimen type, examination, and date range. All four filter states are persisted in per-user browser cookies so the board reopens in the same filtered state across sessions.
Filter cookies are keyed per user ID (e.g. status_filter_specimens_user_7), so each staff member on a shared workstation retains their own preferred board view. The default date range applied on first load is the last 14 days.

Build docs developers (and LLMs) love

Get started for freeTalk to us