bvandeusenandClaude Opus 4.8
3e9b6095dd
Make ThoughtSync installable ("Add to Home Screen") without going
offline-first (the Android app is the real offline client, M5):
- web app manifest (name, icons incl. maskable + SVG, standalone, theme)
- generated PNG icon set + apple-touch-icon + favicon, from committed
SVG sources (a linked-thoughts constellation on the brand tile)
- minimal service worker: installable shell only — caches just an
offline fallback page, never the app shell / hashed assets / API, so
data stays fresh and deploys never serve a stale shell
- register the SW in main.ts (progressive enhancement; failures ignored)
- index.html: manifest/icon links, apple-mobile meta, description
- backend: register the .webmanifest MIME type so it serves as
application/manifest+json
- README: note that install needs a secure context (HTTPS/localhost)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# ThoughtSync
|
|
|
|
Self-hosted personal thought-capture web app in the **FabledSword** family — a
|
|
Google-Keep-style **masonry post-it board** for capturing disparate thoughts in
|
|
under a second, designed to grow into a lightweight second brain (labels, search,
|
|
`[[wiki-links]]`, graph).
|
|
|
|
- **Stack:** Quart (async Python) + Vue 3 + PostgreSQL, Docker, Fabled-Git CI.
|
|
- **Auth:** native email + password (signed-cookie sessions). Multi-user with the
|
|
family owner + direct-share + group-share ACL.
|
|
- **Web-first.** An Android companion is a later, conditional milestone.
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/thoughtsync/ Quart app (app factory, auth, models, ACL, config, db)
|
|
alembic/ async migrations (schema built via `alembic upgrade head`)
|
|
tests/ DB-free unit tests (pytest)
|
|
frontend/ Vue 3 + Vite + TypeScript + Tailwind SPA
|
|
Dockerfile 2-stage build (Vue -> python:3.12-slim runtime)
|
|
docker-compose.yml local app + Postgres stack
|
|
```
|
|
|
|
## Development
|
|
|
|
Backend (needs a Postgres reachable at `THOUGHTSYNC_DATABASE_URL`):
|
|
|
|
```sh
|
|
pip install -e ".[dev]"
|
|
alembic upgrade head
|
|
hypercorn 'thoughtsync.app:create_app()' --bind 0.0.0.0:5000
|
|
```
|
|
|
|
Frontend (proxies `/api` to `:5000`):
|
|
|
|
```sh
|
|
cd frontend
|
|
npm install
|
|
npm run dev # http://localhost:5173
|
|
```
|
|
|
|
Or run it in Docker. **Hot-reload dev stack** (edit code, changes reload live) —
|
|
Postgres + backend + Vite dev server, app at http://localhost:5173:
|
|
|
|
```sh
|
|
docker compose -f docker-compose.dev.yml up
|
|
```
|
|
|
|
Or the **full production image** (SPA baked in) at http://localhost:5000:
|
|
|
|
```sh
|
|
docker compose up --build
|
|
```
|
|
|
|
## Deploy (self-host)
|
|
|
|
A complete two-container stack (app + Postgres) you can copy and run. Save it as
|
|
`docker-compose.yml`, change the two `CHANGE_ME` passwords (they must match), then
|
|
`docker compose up -d`:
|
|
|
|
```yaml
|
|
services:
|
|
db:
|
|
image: postgres:16-alpine
|
|
restart: unless-stopped
|
|
environment:
|
|
POSTGRES_USER: thoughtsync
|
|
POSTGRES_PASSWORD: CHANGE_ME # change this
|
|
POSTGRES_DB: thoughtsync
|
|
volumes:
|
|
- thoughtsync-db:/var/lib/postgresql/data
|
|
healthcheck:
|
|
test: ["CMD-SHELL", "pg_isready -U thoughtsync"]
|
|
interval: 5s
|
|
timeout: 5s
|
|
retries: 10
|
|
|
|
app:
|
|
image: git.fabledsword.com/bvandeusen/thoughtsync:latest # :dev for the current dev build
|
|
restart: unless-stopped
|
|
depends_on:
|
|
db:
|
|
condition: service_healthy
|
|
environment:
|
|
THOUGHTSYNC_DATABASE_URL: postgresql+asyncpg://thoughtsync:CHANGE_ME@db:5432/thoughtsync
|
|
volumes:
|
|
- thoughtsync-data:/var/thoughtsync # uploaded images; omit if you don't use attachments
|
|
ports:
|
|
- "5000:5000"
|
|
|
|
volumes:
|
|
thoughtsync-db:
|
|
thoughtsync-data:
|
|
```
|
|
|
|
Then open `http://<host>:5000` and register — **the first account becomes the admin**.
|
|
|
|
- **Only `THOUGHTSYNC_DATABASE_URL` is required.** `THOUGHTSYNC_SECRET_KEY` is optional; if
|
|
unset, a signing key is generated and persisted in the database (sessions survive restarts).
|
|
- Uploaded images live under the `thoughtsync-data` volume at `/var/thoughtsync`.
|
|
- The app waits for the database and runs migrations (`alembic upgrade head`) automatically on start.
|
|
- **Image tags:** `:latest` (stable, built from `main`) · `:dev` (latest `dev` build) ·
|
|
`:<git-sha>` (immutable, for pinning / rollback).
|
|
- **Install as an app (PWA):** ThoughtSync is installable ("Add to Home Screen" / the
|
|
browser's install button) for an app-like window. Browsers only offer install over a
|
|
**secure context**, so put the app behind a reverse proxy terminating **HTTPS** (or reach
|
|
it via `localhost`) — plain `http://<host>:5000` won't show the install prompt.
|
|
|
|
## Milestones
|
|
|
|
- **M0 — Foundation & Identity** ✅: Quart+Vue+Postgres skeleton, native auth,
|
|
sharing-ACL spine, Fabled-Git CI.
|
|
- **M1 — Capture Core** ✅: note model + masonry board (quick-add, colors, pin,
|
|
edit-in-place, archive, trash+restore).
|
|
- **M1.5 — Roles & DB-backed Settings** ✅: first user is admin, admin Settings UI,
|
|
`DATABASE_URL` is the only required env.
|
|
- M2 — Organize: labels/tags, search, checklists, attachments.
|
|
- M3 — Second-brain seeds: `[[wiki-links]]`, backlinks, graph view, reminders.
|
|
- M4 — Launch hardening: responsive/PWA, settings UI, polish.
|
|
|
|
Work happens on `dev`; `main` is protected (PR-only).
|