# LoreLoom

LoreLoom is a lightweight writing and worldbuilding app for long-form fiction work.

It is currently an early local-first prototype built in the browser, with a focus on writer ownership, clean export, and simple architecture.

## Philosophy

LoreLoom is being built around a few practical ideas:

- local-first by default
- self-hostable later, without forcing a hosted platform
- writer-owned data and exportable content
- AI optional later, not required for the core writing experience
- simple systems before clever systems

## Current Status

LoreLoom is in active development and should be treated as an early prototype.

The current app is useful for experimenting with writing flow and project structure, but it is not production-ready yet.

## Current Features

- projects
- flexible structure tree
- text blocks
- focus mode
- continue in new text block
- codex
- focus mode codex lookup
- command palette
- live writing stats
- native spellcheck
- autosave
- automatic revision snapshots
- backup import/export
- story TXT export
- book preview

## Current Limitations

- backend sync is still early and testing-oriented
- no multi-device sync yet
- no AI yet
- no PDF/wiki export yet
- local account recovery is still admin-managed only, with no email reset flow

## Development Setup

From the repository root:

```bash
cd apps/web
npm install
npm run dev
```

For a production build:

```bash
cd apps/web
npm run build
```

### API Foundation

The backend foundation now lives in `apps/api`.

Install and run it locally:

```bash
cd apps/api
npm install
npm run dev
```

By default the API stores SQLite data in:

- `apps/api/data/loreloom.sqlite`

You can override that path with:

- `DATABASE_PATH=/absolute/path/to/loreloom.sqlite`

Run migrations manually:

```bash
cd apps/api
npm run migrate
```

Build the API:

```bash
cd apps/api
npm run build
```

Run a basic API smoke test against a running server:

```bash
cd apps/api
npm run smoke
```

If the API is not running on `http://127.0.0.1:8787`, set:

```bash
API_BASE_URL=http://your-host:8787 npm run smoke
```

### Local Accounts

LoreLoom uses local self-hosted accounts rather than public signup.

- the first account is created through one-time admin setup
- additional users can be created by an admin inside the app
- there is no public signup flow
- password resets are admin-generated temporary passwords shown once in the UI
- users can change their own password after sign-in
- there is no email recovery yet

### SQLite Backups

For the current API foundation, the safest backup flow is:

1. stop the API
2. copy the whole `apps/api/data/` directory

That preserves the SQLite database file along with its WAL-sidecar state if present.

If you use a custom `DATABASE_PATH`, back up the directory that contains that SQLite file instead.

## Docker Compose Testing

LoreLoom now has a simple Raspberry Pi friendly Docker Compose setup for LAN and home testing.

This is still early testing software. Use it for experiments and personal evaluation, not as a production-hardened deployment.

Start the stack from the repository root:

```bash
docker compose up --build -d
```

Stop it:

```bash
docker compose down
```

View logs:

```bash
docker compose logs -f
```

The app is served at:

- [http://localhost:8088](http://localhost:8088)

### Compose Data Persistence

The Compose setup keeps SQLite data on the host at:

- `./data/api/loreloom.sqlite`

Inside the API container, that file is mounted at:

- `/data/loreloom.sqlite`

The API is only exposed inside the Compose network. The web container proxies `/api` and `/health` to it.

### Backups In Docker

For the Compose setup, the safest SQLite backup flow is:

1. stop the stack with `docker compose down`
2. copy the `./data/api/` directory somewhere safe

That preserves the main SQLite database file and any SQLite sidecar files if present.

### LAN And Reverse Proxy Notes

- The default Compose setup is intended for local machine and home-LAN testing.
- If you later place LoreLoom behind a reverse proxy, keep the web container as the public entry point and continue to leave the API unexposed on the host unless you have a specific reason to publish it.
- The frontend uses a compatibility-safe client ID helper so project and content creation still works in non-secure LAN HTTP contexts where `crypto.randomUUID()` may be unavailable.

## Diagnostic Bundle Export

Testers can export a manual diagnostic bundle from the LoreLoom diagnostics page:

1. open the app
2. go to `Diagnostics`
3. click `Export Diagnostic Bundle`

The current export format is a `.json` file so it can be inspected easily before sharing.

### What The Diagnostic Bundle Includes

- app version and build timestamp when available
- frontend environment details such as browser, origin, and storage availability
- backend health and backend diagnostic/config information when reachable
- diagnostics summary counts
- recent diagnostics events
- sync statuses
- sync errors and conflicts
- approximate local storage usage when available

### What The Diagnostic Bundle Excludes

- manuscript text
- text block content
- codex content
- revision snapshot content
- project titles
- text block titles
- codex titles
- search queries

Sharing is always manual. LoreLoom does not upload, email, or send this bundle anywhere automatically.

If a tester or developer asks for more context, the current community/support channel is the LoreLoom Discord:

- [Join the LoreLoom Discord](https://discord.gg/ktUw2gsyAW)

Use it for help, bug reports, suggestions, and tester feedback.

## Project Principles

- the writing experience should still work without AI
- data should stay understandable and portable
- export matters
- infrastructure should stay modest as long as possible
- the app should remain usable on low-power self-hosted hardware later
- core writing flow should stay calm and low-friction

## Roadmap

Likely next directions include:

- self-hosted backend
- desktop helper / local AI worker
- wiki / PDF export
- manual codex linking
- optional AI weaving / indexing
- sync and backup improvements

## Notes

- The current web app lives in [apps/web](/Users/zennondeboer/Documents/LoreLoom/apps/web).
- The current product direction is described further in [docs/vision.md](/Users/zennondeboer/Documents/LoreLoom/docs/vision.md) and [docs/data-model.md](/Users/zennondeboer/Documents/LoreLoom/docs/data-model.md).
