symptom-journal

name	symptom-journal
description	Log and track personal health symptoms with severity ratings, pattern analysis, trigger correlation, and PDF report generation for doctor visits. Use when a user needs to record health symptoms, review symptom history, analyze patterns, or prepare a doctor visit summary.

symptom-journal

A local-first symptom tracking tool. All data stays on the user's device.

When to use

• User wants to log a new symptom occurrence
• User wants to review symptom history or frequency
• User needs to analyze patterns or triggers
• User is preparing for a doctor visit and needs a report
• User wants to track medication correlations with symptoms

Privacy model

All symptom data is stored locally in SQLite at ./data/journal.db. No network requests are made for data. PDF export is generated locally. No telemetry or analytics.

Prerequisites

• symptom-journal server running: pnpm dev or docker compose up -d
• Server accessible at http://localhost:3847 (default)

Installation

git clone <repo>
cd symptom-journal
pnpm install
pnpm dev
# App runs at http://localhost:3847

Or with Docker:

docker compose up -d
# App runs at http://localhost:3847

Key operations via API

Log a symptom

curl -X POST http://localhost:3847/api/symptoms \
  -H "Content-Type: application/json" \
  -d '{
    "symptom_type_id": 1,
    "severity": 5,
    "time_of_day": "morning",
    "logged_at": "2026-03-20T09:14:00",
    "notes": "Context notes here"
  }'

List recent symptoms

curl "http://localhost:3847/api/symptoms?per_page=20"

Get pattern data

curl "http://localhost:3847/api/patterns/frequency?from=2026-02-01&to=2026-03-20"

Generate PDF report

curl -X POST http://localhost:3847/api/reports/export/pdf \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-02-01","to":"2026-03-20","include_notes":true}' \
  --output report.pdf

API Reference

Endpoint	Method	Description
/api/symptoms	GET	List symptoms (supports from, to, type_id query params)
/api/symptoms	POST	Create symptom entry
/api/symptoms/:id	GET	Single entry detail
/api/symptoms/:id	PUT	Update entry
/api/symptoms/:id	DELETE	Delete entry
/api/symptom-types	GET	List symptom types
/api/symptom-types	POST	Create custom type
/api/patterns/frequency	GET	Frequency time series
/api/patterns/severity	GET	Severity trend data
/api/patterns/triggers	GET	Trigger correlation data
/api/patterns/heatmap	GET	Calendar heatmap data
/api/medications	GET	List medications
/api/medications	POST	Add medication
/api/reports/export/pdf	POST	Generate and download PDF
/api/settings	GET	Get settings
/api/settings	PATCH	Update settings

Severity scale

Range	Label	Color
1-3	Low / manageable	Green
4-6	Moderate	Amber
7-10	High / severe	Red

Environment Variables

Variable	Default	Description
PORT	3847	Server port
DATA_DIR	./data	SQLite database location
EXPORT_DIR	./exports	PDF export temp directory
LOG_LEVEL	info	debug / info / warn / error
PIN_LOCK	0	1 = require PIN on startup
NODE_ENV	development	development / production

Symptom type IDs (built-in)

ID	Name	Category
1	Headache	Pain / Neurological
2	Migraine	Pain / Neurological
3	Fatigue	Energy
4	Nausea	Digestive
5	Joint Pain	Pain / Musculoskeletal
6	Dizziness	Neurological
7	Anxiety	Mental / Emotional
8	Insomnia	Sleep

Troubleshooting

Port already in use

Change PORT in environment or .env file.

Database file permission error

Ensure DATA_DIR is writable by the server process. Default is ./data/.

PDF generation fails

Check that EXPORT_DIR is writable. Ensure pdfkit is installed (pnpm install).