# snotes — Agent Guide

## Project Overview

A multi-user hosted markdown notes app. Notes are plain `.md` files on a mounted
filesystem (NAS at `/mnt/aura/snotes`), while metadata, tags, history, and a
full-text search index live in SQLite. Built with FastAPI + a vanilla-JS SPA that
embeds TipTap (ProseMirror) for the editor.

## Essential Commands

| Action | Command |
|---|---|
| Dev server | `./run-local` (or `uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000`) |
| Run tests | `uv run pytest` |
| Lint | `uv run ruff check .` |
| Format | `uv run ruff format .` |
| Install deps | `uv sync` |
| Build Docker | `docker compose build` |

## Project Structure

```
snotes/
├── backend/
│   ├── main.py       # FastAPI app, routes, lifespan, auth dependency
│   ├── config.py     # pydantic-settings, reads .env
│   ├── database.py   # aiosqlite: schema, seed users, list_users
│   ├── notes.py      # note CRUD, tag extraction, FTS index, history
│   ├── auth.py       # LAN vs remote gate + signed session cookie
│   └── models.py     # Pydantic request models
├── static/
│   ├── index.html    # SPA shell; loads marked, turndown, app.js (ESM)
│   ├── app.js        # SPA client + TipTap editor (esm.sh CDN)
│   ├── app.css       # Hyper-inspired stylesheet
│   └── snotes-main.png  # logo + favicon (copied from assets/)
├── tests/
│   ├── conftest.py   # LAN + remote ASGI client fixtures (temp DB + data dir)
│   └── test_main.py
├── Dockerfile
├── docker-compose.yml   # port 8019, mounts /mnt/aura/snotes
├── pyproject.toml
└── .env.example
```

## API Routes

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/me` | Current user + auth mode |
| `GET` | `/api/users` | List users |
| `POST` | `/api/users/select` | Set user cookie |
| `POST` | `/api/auth/login` | Remote password → auth cookie |
| `GET/POST` | `/api/notes` | List (current user) / create |
| `GET` | `/api/notes/recent` | Recent notes across all users |
| `GET/PUT/DELETE` | `/api/notes/{id}` | Read / update / soft-delete |
| `GET` | `/api/notes/{id}/history` | Version history |
| `GET` | `/api/tags` | Tag frequency |
| `GET` | `/api/search?q=` | FTS5 search |

## Non-obvious Behaviors

1. **Auth model**: the LAN gate (in `auth.is_lan`) matches the client IP against
   `LAN_CIDRS`. When remote, a signed `snotes_auth` cookie (itsdangerous) is
   required. User selection is a separate plain `snotes_user` cookie.
2. **Client IP**: read from `X-Forwarded-For` first, else `request.client.host` —
   set the latter in tests via `ASGITransport(..., client=(ip, port))`.
3. **Markdown round-trip**: the editor works on HTML. On load, `marked` converts
   markdown → HTML into TipTap; on save, `turndown` converts TipTap HTML →
   markdown. The stored `.md` file is the source of truth for search/tags.
4. **Storage split**: note *content* lives in `DATA_DIR/<user>/<uuid>.md`; all
   metadata (title, tags, timestamps, history) lives in SQLite. The filename is a
   random uuid hex, never the title (titles change freely).
5. **Soft delete**: deletes set `notes.deleted_at`, remove the `.md` file, and
   write a `delete` history row.
6. **FTS sync**: every save deletes + re-inserts the note's FTS row (title+body);
   tags are normalized into `tags`/`note_tags` join tables.

## Gotchas

- The frontend loads TipTap via `esm.sh` and marked/turndown via jsDelivr — the
  app needs internet access on first editor load (or vendor these locally later).
- `notes.py` opens a new `aiosqlite` connection per operation (same pattern as
  `tasky`); fine for a small personal corpus, not for hot paths.