From a5f1f891767a9495f8263f5194a6df1ee38a1bab Mon Sep 17 00:00:00 2001 From: lotherk Date: Fri, 27 Mar 2026 15:11:36 +0000 Subject: [PATCH] v0.1.6: Add comprehensive API docs and additional documentation pages --- AGENTS.md | 1 + VERSION.txt | 2 +- www/docs/ai-providers.html | 7 ++ www/docs/api.html | 218 ++++++++++++++++++++++++++++++++++++ www/docs/configuration.html | 144 ++++++++++++++++++++++++ www/docs/events.html | 125 +++++++++++++++++++++ www/docs/export-import.html | 125 +++++++++++++++++++++ www/docs/index.html | 10 ++ www/docs/installation.html | 10 ++ www/docs/quick-start.html | 10 ++ 10 files changed, 651 insertions(+), 1 deletion(-) create mode 100644 www/docs/api.html create mode 100644 www/docs/configuration.html create mode 100644 www/docs/events.html create mode 100644 www/docs/export-import.html diff --git a/AGENTS.md b/AGENTS.md index 382bf96..c7db7a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -233,6 +233,7 @@ Version is managed via `VERSION.txt` (single source of truth). All other version - Never commit actual version numbers in source files ## Version History +- 0.1.6: Add comprehensive API docs and additional documentation pages - 0.1.5: Fix ENV syntax in website Dockerfile - 0.1.4: Version links to git releases on website - 0.1.3: Add VERSION to website build diff --git a/VERSION.txt b/VERSION.txt index 446ba66..a192233 100644 --- a/VERSION.txt +++ b/VERSION.txt @@ -1 +1 @@ -0.1.4 \ No newline at end of file +0.1.6 \ No newline at end of file diff --git a/www/docs/ai-providers.html b/www/docs/ai-providers.html index 1445828..7a476b5 100644 --- a/www/docs/ai-providers.html +++ b/www/docs/ai-providers.html @@ -30,9 +30,16 @@ Installation Quick Start +
+

Configuration

+ Environment + API Reference +

Features

+ Events AI Providers + Export & Import
diff --git a/www/docs/api.html b/www/docs/api.html new file mode 100644 index 0000000..f94307d --- /dev/null +++ b/www/docs/api.html @@ -0,0 +1,218 @@ + + + + + + API Reference - DearDiary + + + + + + +
+ + +
+

API Reference

+ +

The DearDiary API is REST-based with JSON responses. All endpoints return a consistent format.

+ +

Response Format

+

All responses follow this structure:

+ 
{
+  "data": { ... } | null,
+  "error": { "code": "ERROR_CODE", "message": "..." } | null
+}
+ +

Authentication

+

Include your API key in the Authorization header:

+ 
Authorization: Bearer <your-api-key>
+ +

Endpoints

+ +

Events

+ +

GET /api/v1/events?date=YYYY-MM-DD

+

List events for a specific date.

+ 
// Response
+{
+  "data": [
+    {
+      "id": "evt_xxx",
+      "date": "2026-03-27",
+      "type": "text",
+      "content": "Had coffee with Sarah",
+      "latitude": 40.7128,
+      "longitude": -74.0060,
+      "placeName": "New York, NY",
+      "createdAt": "2026-03-27T08:30:00Z"
+    }
+  ]
+}
+ +

POST /api/v1/events

+

Create a new event.

+ 
// Request body
+{
+  "date": "2026-03-27",
+  "type": "text",        // text, photo, voice, health
+  "content": "Event content"
+}
+
+// Response
+{
+  "data": {
+    "id": "evt_xxx",
+    "date": "2026-03-27",
+    "type": "text",
+    "content": "Event content",
+    "createdAt": "2026-03-27T10:00:00Z"
+  }
+}
+ +

DELETE /api/v1/events/:id

+

Delete an event. Only works if no journal exists for that date.

+ +

Journals

+ +

GET /api/v1/journal/:date

+

Get diary page for a specific date.

+ 
{
+  "data": {
+    "id": "jrn_xxx",
+    "date": "2026-03-27",
+    "title": "A Productive Tuesday",
+    "content": "Today was filled with...",
+    "eventCount": 8,
+    "generatedAt": "2026-03-27T20:00:00Z"
+  }
+}
+ +

POST /api/v1/journal/generate/:date

+

Generate a diary page from events. Starts an async task.

+ 
// Request body (optional)
+{
+  "instructions": "Focus on the meeting with the client"
+}
+
+// Response
+{
+  "data": {
+    "taskId": "tsk_xxx",
+    "status": "pending"
+  }
+}
+ +

PUT /api/v1/journal/:date

+

Update journal title and content.

+ 
// Request body
+{
+  "title": "New Title",
+  "content": "Updated content..."
+}
+ +

DELETE /api/v1/journal/:date

+

Delete journal. This unlocks events so they can be modified.

+ +

Tasks

+ +

GET /api/v1/journal/:date/tasks

+

Get generation tasks for a journal.

+ 
{
+  "data": [
+    {
+      "id": "tsk_xxx",
+      "type": "generate",
+      "status": "completed",  // pending, processing, completed, failed
+      "title": "A Great Day",
+      "provider": "groq",
+      "model": "llama-3.3-70b-versatile",
+      "createdAt": "2026-03-27T20:00:00Z",
+      "completedAt": "2026-03-27T20:00:30Z"
+    }
+  ]
+}
+ +

Journals List

+ +

GET /api/v1/journals?page=1&limit=10

+

List all diary pages with pagination.

+ +

GET /api/v1/days

+

List days with journal info and excerpts.

+ +

Settings

+ +

GET /api/v1/settings

+

Get current user settings.

+ +

PUT /api/v1/settings

+

Update user settings.

+ 
{
+  "aiProvider": "groq",
+  "aiApiKey": "gsk_xxx",
+  "aiModel": "llama-3.3-70b-versatile",
+  "useSystemDefault": false
+}
+ +

Data Management

+ +

GET /api/v1/export

+

Export all user data as JSON.

+ 
{
+  "data": {
+    "version": "0.1.0",
+    "exportedAt": "2026-03-27T12:00:00Z",
+    "events": [...],
+    "journals": [...],
+    "tasks": [...],
+    "settings": {...}
+  }
+}
+ +

POST /api/v1/import

+

Import data from export file.

+ +

GET /api/v1/health

+

Health check endpoint (no auth required).

+ 
{ "status": "ok" }
+ +
+ ← Configuration + Next: Events → +
+
+
+ + \ No newline at end of file diff --git a/www/docs/configuration.html b/www/docs/configuration.html new file mode 100644 index 0000000..c4d1b00 --- /dev/null +++ b/www/docs/configuration.html @@ -0,0 +1,144 @@ + + + + + + Configuration - DearDiary + + + + + + +
+ + +
+

Configuration

+ +

DearDiary uses environment variables for configuration. Create a .env file in the project root.

+ +

Environment Variables

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDefaultDescription
BACKEND_JWT_SECRETRequiredSecret key for JWT token signing. Generate a strong random string.
BACKEND_PORT3001Port for the backend API server
BACKEND_CORS_ORIGIN*CORS allowed origins (comma-separated)
BACKEND_REGISTRATION_ENABLEDfalseAllow new user registration (true/false)
BACKEND_DATABASE_URLfile:/data/deardiary.dbSQLite database path
BACKEND_MEDIA_DIR/data/mediaDirectory for uploaded media files
BACKEND_DEFAULT_USER_EMAIL-Email for default admin user (created on first start)
BACKEND_DEFAULT_USER_PASSWORD-Password for default admin user
BACKEND_DEFAULT_AI_PROVIDERgroqDefault AI provider (groq, openai, anthropic, ollama, lmstudio)
BACKEND_DEFAULT_AI_MODELllama-3.3-70b-versatileDefault AI model
BACKEND_DEFAULT_AI_API_KEY-Default API key for AI provider
BACKEND_DEFAULT_AI_BASE_URL-Custom API base URL (for local providers)
+ +

Example .env File

+ 
BACKEND_JWT_SECRET=your-super-secret-key-change-this
+BACKEND_CORS_ORIGIN=https://your-domain.com
+BACKEND_REGISTRATION_ENABLED=false
+BACKEND_DEFAULT_USER_EMAIL=admin@your-domain.com
+BACKEND_DEFAULT_USER_PASSWORD=change-me-after-login
+BACKEND_DEFAULT_AI_PROVIDER=groq
+BACKEND_DEFAULT_AI_API_KEY=your-groq-api-key
+ +

Using System Default AI Settings

+

When BACKEND_DEFAULT_AI_* variables are set, all new users will use those settings by default. Users can override these in their personal settings.

+ +
+ Tip: For production, always set BACKEND_REGISTRATION_ENABLED=false and create the admin user via BACKEND_DEFAULT_USER_EMAIL and BACKEND_DEFAULT_USER_PASSWORD. +
+ +
+ ← Installation + Next: API Reference → +
+
+
+ + \ No newline at end of file diff --git a/www/docs/events.html b/www/docs/events.html new file mode 100644 index 0000000..38687fe --- /dev/null +++ b/www/docs/events.html @@ -0,0 +1,125 @@ + + + + + + Events - DearDiary + + + + + + +
+ + +
+

Events

+ +

Events are the building blocks of your diary. They're quick captures throughout the day that get transformed into thoughtful diary pages.

+ +

Event Types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescriptionExample
TextPlain text notes"Coffee with Mike at 9am"
PhotoImage capturesSunset from the office window
VoiceVoice memosIdeas for the project
HealthHealth-related notes"Feeling tired, had 6 hours sleep"
+ +

Automatic Metadata

+

Every event captures:

+
    +
  • Timestamp - When the event was created
    • +
  • Date - The calendar date (YYYY-MM-DD)
    • +
  • Location - GPS coordinates (if browser allows)
    • +
  • Place Name - Reverse geocoded address
    • +
+ +

Immutability

+

Once a diary page is generated for a day, all events for that day become locked:

+
    +
  • You cannot edit or delete individual events
    • +
  • This preserves the authenticity of your record
    • +
  • Your past stays untouched by today's perspective
    • +
+ +
+ To unlock events: Delete the diary page for that date. Events become editable again. +
+ +

Event Stream

+

The Today page shows your event stream for the current day:

+
    +
  • Newest events appear at the top
    • +
  • Events show time, type, content, and location
    • +
  • Quick add via text input or keyboard shortcut (Ctrl+J)
    • +
+ +

Browse Past Days

+

Use the calendar view or date navigator to view events from any day:

+
    +
  • Click any date to see that day's events
    • +
  • Days with diary pages are marked
    • +
  • Navigate with arrow keys in the date picker
    • +
+ +
+ ← API Reference + Next: Export & Import → +
+
+
+ + \ No newline at end of file diff --git a/www/docs/export-import.html b/www/docs/export-import.html new file mode 100644 index 0000000..bf6d6db --- /dev/null +++ b/www/docs/export-import.html @@ -0,0 +1,125 @@ + + + + + + Export & Import - DearDiary + + + + + + +
+ + +
+

Export & Import

+ +

Your data belongs to you. Export everything anytime, import to restore or migrate.

+ +

Export

+

Go to Settings and click Export Data. This downloads a JSON file containing:

+
    +
  • version - DearDiary version
    • +
  • exportedAt - Timestamp
    • +
  • settings - Your AI and app settings
    • +
  • events - All event records with metadata
    • +
  • journals - All diary pages
    • +
  • tasks - Generation history
    • +
+ +

Import

+

Go to Settings and click Import Data. Select your export file.

+ +

Import Behavior

+
    +
  • Duplicates skipped - Events matched by date + content + timestamp
    • +
  • Journals matched by date - Won't create duplicate diaries
    • +
  • Tasks linked to journals - Generation history preserved
    • +
  • Settings overwritten - Your current settings are replaced
    • +
+ +

Version Compatibility

+

DearDiary checks export versions:

+
    +
  • Minimum supported: 0.0.3
    • +
  • Warnings shown for older/newer versions
    • +
  • May lose data with very old exports
    • +
+ +
+ Tip: Export regularly as a backup. Store exports in a safe place. +
+ +

Why Export?

+
    +
  • Backup - Protect against data loss
    • +
  • Migration - Move to a new server
    • +
  • Privacy - Keep a local copy
    • +
  • Analysis - Work with your data in other tools
    • +
+ +

Export Format

+ 
{
+  "version": "0.1.0",
+  "exportedAt": "2026-03-27T12:00:00Z",
+  "settings": {
+    "aiProvider": "groq",
+    "aiApiKey": "gsk_xxx",
+    ...
+  },
+  "events": [
+    {
+      "id": "evt_xxx",
+      "date": "2026-03-27",
+      "type": "text",
+      "content": "Had coffee with Sarah",
+      "latitude": 40.7128,
+      "longitude": -74.0060,
+      "placeName": "New York, NY",
+      "createdAt": "2026-03-27T08:30:00Z"
+    }
+  ],
+  "journals": [...],
+  "tasks": [...]
+}
+ +
+ ← Events + Next: AI Providers → +
+
+
+ + \ No newline at end of file diff --git a/www/docs/index.html b/www/docs/index.html index 1263a7a..fba830b 100644 --- a/www/docs/index.html +++ b/www/docs/index.html @@ -29,7 +29,17 @@

Getting Started

Installation Quick Start + +
+

Configuration

+ Environment + API Reference +
+
+

Features

+ Events AI Providers + Export & Import
diff --git a/www/docs/installation.html b/www/docs/installation.html index 3ee87be..67f5845 100644 --- a/www/docs/installation.html +++ b/www/docs/installation.html @@ -29,7 +29,17 @@

Getting Started

Installation Quick Start + +
+

Configuration

+ Environment + API Reference +
+
+

Features

+ Events AI Providers + Export & Import
diff --git a/www/docs/quick-start.html b/www/docs/quick-start.html index bbd4ce1..1f9e782 100644 --- a/www/docs/quick-start.html +++ b/www/docs/quick-start.html @@ -29,7 +29,17 @@

Getting Started

Installation Quick Start + +
+

Configuration

+ Environment + API Reference +
+
+

Features

+ Events AI Providers + Export & Import