Clinical Records: Structured Medical Histories in MELIKA

MELIKA’s clinical records system (historias_clinicas) gives doctors a structured workspace to document every consultation — from chief complaint through diagnosis, vitals, and treatment plan. Records are tightly coupled to a completed appointment, can be supplemented with clarification or evolution notes at any time, and support external document attachments plus full PDF export. Strict role-based access ensures only the treating doctor can author a record, while the patient retains read-only visibility into their own health history.

What a Clinical Record Contains

Each historia_clinica is linked one-to-one with a managed appointment via id_cita. The table is broad and covers narrative, vitals, diagnosis, treatment, and administrative signature fields.

Core narrative fields

Field	Type	Required	Description
`tipo_registro`	`varchar`	✅ Yes	`'historia_principal'`, `'nota_aclaracion'`, or `'nota_evolucion'`
`estado`	`varchar`	✅ Yes	Record status — always `'activo'` on creation
`motivo_consulta`	`text`	✅ Yes	Chief complaint — the patient’s stated reason for the visit
`anamnesis`	`text`	✅ Yes	Clinical history and symptom narrative taken from the patient
`antecedentes_patologicos`	`text`	✅ Yes	Pathological background (chronic conditions, prior illnesses)
`antecedentes_alergicos`	`text`	✅ Yes	Known allergies
`examen_fisico`	`text`	✅ Yes	Physical examination findings recorded by the doctor
`diagnostico_cie10`	`varchar`	✅ Yes	ICD-10 / CIE-10 diagnostic code (e.g., `I10` for hypertension)
`descripcion_diagnostico`	`text`	✅ Yes	Plain-language description of the diagnosis
`plan_tratamiento`	`text`	✅ Yes	Treatment plan, follow-up instructions, referrals
`antecedentes_quirurgicos`	`text`	No	Surgical history
`antecedentes_familiares`	`text`	No	Relevant family medical history
`antecedentes_ginecoobstetricos`	`text`	No	Gynecological / obstetric history
`habitos`	`text`	No	Lifestyle habits (smoking, alcohol, exercise)
`exploracion_por_sistemas`	`text`	No	Systems review findings
`ordenes_medicas`	`text`	No	Supplementary medical orders
`recomendaciones`	`text`	No	Patient recommendations and aftercare instructions
`incapacidad_dias`	`integer`	No	Medical leave days granted
`observaciones`	`text`	No	Additional clinical observations
`eps_aseguradora`	`varchar`	No	Patient’s health insurer
`contacto_responsable_nombre`	`varchar`	No	Name of responsible contact
`contacto_responsable_telefono`	`varchar`	No	Phone of responsible contact

Vitals fields

Field	Type	Description
`tension_arterial_sistolica`	`numeric`	Systolic blood pressure (mmHg)
`tension_arterial_diastolica`	`numeric`	Diastolic blood pressure (mmHg)
`frecuencia_cardiaca`	`numeric`	Heart rate (bpm)
`frecuencia_respiratoria`	`numeric`	Respiratory rate (breaths/min)
`temperatura_corporal`	`numeric`	Body temperature (°C)
`peso_kg`	`numeric`	Weight in kilograms
`talla_cm`	`numeric`	Height in centimeters
`imc`	`numeric`	Body Mass Index — calculated automatically from `peso_kg` and `talla_cm`

Prescription and signature fields

Field	Type	Description
`medicamentos_recetados`	`jsonb`	Prescribed medications stored as `{ "texto": "..." }` — see Prescribed Medications below
`medico_nombre_firma`	`varchar`	✅ Required — Doctor’s full name for the record signature
`medico_cedula_firma`	`varchar`	Doctor’s ID number for the signature
`medico_rethus_firma`	`varchar`	✅ Required — Doctor’s RETHUS professional registration number
`id_historia_original`	`integer`	FK to the parent `historia_principal` — set on clarification/evolution notes

The imc (BMI) is always computed server-side from peso_kg and talla_cm. Do not send it in the request body — it will be calculated and stored automatically.

Doctor Workflow

Complete the Appointment

Once a patient’s appointment reaches its scheduled time, the treating doctor navigates to the appointment and selects Gestionar, marking the cita as completada or no_asistio via PATCH /historias/gestionar-cita/:id.

Create the Clinical Record

The doctor fills in the historia_clinica fields. The mandatory fields listed above must all be present. The request also accepts optional recetas and examenes arrays, which are inserted into separate recetas_medicas and ordenes_examenes tables within the same database transaction.Creating a clinical record automatically sets the linked cita.estado to 'completada'.

POST /historias
Content-Type: application/json

{
  "id_cita": 42,
  "motivo_consulta": "Dolor de cabeza recurrente con náuseas",
  "anamnesis": "Paciente refiere episodios de cefalea 3 veces por semana durante el último mes",
  "antecedentes_patologicos": "Hipertensión arterial diagnosticada hace 5 años",
  "antecedentes_alergicos": "Alergia a penicilina",
  "examen_fisico": "TA 130/85 mmHg, FC 78 lpm. Sin déficit neurológico focal.",
  "diagnostico_cie10": "G43.9",
  "descripcion_diagnostico": "Migraña sin aura, sin mención de estado migrañoso",
  "plan_tratamiento": "Iniciar profilaxis con Amitriptilina 10mg/noche. Control en 4 semanas.",
  "medicamentos_recetados": "Amitriptilina 10mg, 1 tableta vía oral cada noche por 30 días",
  "medico_nombre_firma": "Dr. Carlos Vargas Mejía",
  "medico_rethus_firma": "RM-2019-04521",
  "peso_kg": 72,
  "talla_cm": 170,
  "recetas": [
    {
      "medicamento": "Amitriptilina",
      "dosis": "10mg",
      "frecuencia": "cada noche",
      "duracion": "30 días",
      "via_administracion": "oral"
    }
  ],
  "examenes": []
}

Add Clarification or Evolution Notes (Optional)

After saving the record, the doctor can append a clarification (nota_aclaracion) or evolution (nota_evolucion) note at any time. The note is a new row in historias_clinicas linked to the original via id_historia_original. Both routes reach the same controller.

POST /historias/:id/aclaracion
Content-Type: application/json

{
  "tipo_registro": "nota_aclaracion",
  "motivo_consulta": "Actualización tras resultados de MRI",
  "medico_nombre_firma": "Dr. Carlos Vargas Mejía",
  "medico_rethus_firma": "RM-2019-04521"
}

tipo_registro must be either "nota_aclaracion" or "nota_evolucion". All other clinical fields are optional on notes but follow the same shape as the main record.The same endpoint is also reachable via PUT /historias/:id for backward compatibility.

Prescribed Medications

The medicamentos_recetados column is a jsonb field that stores prescriptions as a plain text object: { "texto": "..." }. The value sent by the client may be a plain string or an object with a texto key — the server normalizes both forms before persisting.

{ "texto": "Amitriptilina 10mg, 1 tableta oral cada noche × 30 días. Ibuprofeno 400mg cada 8h SOS." }

When the record is returned to the frontend, the server deserializes this back to the plain string stored in texto for display and PDF rendering.

For structured per-medication rows with dosing fields, use the recetas array in the POST /historias request body instead. Each entry is stored in the separate recetas_medicas table with columns: medicamento, dosis, frecuencia, duracion, via_administracion, and indicaciones.

Retrieving Clinical Records

By Appointment
By Record ID (Full)
Patient History

Returns the historia_principal for a given appointment, along with its linked aclaraciones (clarification/evolution notes), recetas, and examenes arrays.

GET /historias/cita/:id_cita

When no record has been created yet, returns { historia: null, aclaraciones: [], recetas: [], examenes: [] } (not a 404).

Returns a complete clinical record including all joined patient and doctor data (name, ID document, birth date, city, gender, specialty, appointment date).

GET /historias/:id/completa

Returns a summary list of all historia_principal records for a given patient, ordered by creation date descending. Includes CIE-10 code, diagnosis description, treating doctor, specialty, and total clarification count per record.

GET /historias/paciente/:id_paciente

Clinical Documents

External clinical documents — such as laboratory results, imaging reports, or referral letters — can be registered and associated with a clinical record.

Register a Document
List Documents
Hide a Document (Patient)

POST /historias/documentos
Content-Type: application/json

{
  "id_historia": 15,
  "id_paciente": 8,
  "tipo_documento": "formula_medica",
  "nombre_archivo": "formula_amitriptilina.pdf",
  "url_pdf": "https://storage.melika.app/docs/formula-42.pdf",
  "descripcion": "Fórmula médica post-consulta neurología"
}

Required fields: id_paciente, tipo_documento, url_pdf.Allowed tipo_documento values depend on the caller’s role:

Role	Allowed types
`medico`	`formula_medica`, `orden_examen`, `historia_clinica`
`paciente`	`documento_externo`

Doctors may only register documents for patients with whom they have at least one shared appointment.

GET /historias/documentos/paciente/:id_paciente

Patients see only documents where oculto_paciente = FALSE. Doctors see all documents for patients linked to their caseload.

Patients can hide documents they uploaded (origen = 'paciente') from their visible record view. Documents created by the doctor cannot be hidden.

PATCH /historias/documentos/:id/ocultar

Hiding a document only affects the patient’s view. The document remains in the database and is still visible to the treating doctor.

PDF Export and In-Browser Viewer

MELIKA provides full PDF generation and in-browser viewing of clinical records, entirely client-side.

PDF Generation

The PlantillaHistoriaPDF.jsx component uses @react-pdf/renderer to compile all clinical record fields — including the medication text, CIE-10 code, and clarification notes — into a downloadable PDF. Three templates are available: Historia Clínica, Fórmula Médica, and Orden de Exámenes.

In-Browser Viewer

The VisorPDFModal.jsx component renders the generated PDF directly in a modal overlay, allowing patients to review the document without leaving the application or downloading the file.

PDF generation happens entirely in the browser via @react-pdf/renderer — no server-side rendering pipeline is required. The resulting file can be downloaded directly from the viewer modal.

Access Control

Clinical records enforce strict role-based access. Authorization is checked at the controller level before any database write.

Role	Permissions
`medico` (treating doctor)	Create record, add clarification/evolution notes, register documents, manage appointment state
`medico` (other doctor)	Read records only if they have at least one shared appointment with the patient
`paciente`	Read their own records and documents; hide patient-uploaded documents from their view

Only the treating doctor (the medico linked to the original cita) can create a clinical record for that appointment. Other doctors can view but cannot author records they did not originate.

Get Started

Core Features

User Roles

Clinical Records: Structured Medical Histories in MELIKA

What a Clinical Record Contains

Core narrative fields

Vitals fields

Prescription and signature fields

Doctor Workflow

Prescribed Medications

Retrieving Clinical Records

Clinical Documents

PDF Export and In-Browser Viewer

PDF Generation

In-Browser Viewer

Access Control

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Documentation Index

​What a Clinical Record Contains

​Core narrative fields

​Vitals fields

​Prescription and signature fields

​Doctor Workflow

​Prescribed Medications

​Retrieving Clinical Records

​Clinical Documents

​PDF Export and In-Browser Viewer

PDF Generation

In-Browser Viewer

​Access Control

Build docs developers (and LLMs) love

What a Clinical Record Contains

Core narrative fields

Vitals fields

Prescription and signature fields

Doctor Workflow

Prescribed Medications

Retrieving Clinical Records

Clinical Documents

PDF Export and In-Browser Viewer

Access Control