symptom-journal

# 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

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

Or with Docker:

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

## Key operations via API

### Log a symptom

```bash
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

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

### Get pattern data

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

### Generate PDF report

```bash
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`).