140 lines
6.2 KiB
Markdown
140 lines
6.2 KiB
Markdown
# ClaudeDo Online Inbox — API Contract & VPS build prompt
|
|
|
|
Status: handoff doc. The **server side** (API + minimal web client) is built and deployed
|
|
VPS-side by a separate Claude instance. This file is the source of truth for the contract
|
|
both ends implement against. The desktop client in this repo is built to match it.
|
|
|
|
---
|
|
|
|
## 1. Concept
|
|
|
|
ClaudeDo is a local desktop app that runs tasks autonomously via the Claude CLI; it is
|
|
normally fully local (SQLite). The **Online Inbox** is an optional service that lets the
|
|
single owner view their task lists and add new tasks from a phone/browser. The desktop app
|
|
syncs against it.
|
|
|
|
**Governing rule:** the online store mirrors EXACTLY the desktop's `Idle` backlog — nothing
|
|
else. A task is present online only while it is `Idle` on the desktop. The moment the user
|
|
queues it locally, the desktop removes it from the online store. Running / WaitingForReview /
|
|
Done / Failed / Cancelled tasks never appear online.
|
|
|
|
Sync directions (each one-way per entity → no conflict resolution needed):
|
|
|
|
- **Lists**: desktop → online only. Desktop is the source of truth (full-replace catalog).
|
|
- **Idle tasks**: desktop mirrors its Idle backlog up; the web can create new ones, which the
|
|
desktop pulls down and then owns.
|
|
|
|
Single user. Both the desktop and the web client authenticate as the **same Zitadel user**.
|
|
|
|
## 2. Idle backlog definition (desktop side)
|
|
|
|
The desktop mirrors only "real" backlog items, not planning internals:
|
|
|
|
- `Status == Idle`
|
|
- `ParentTaskId == null` (no planning/improvement children)
|
|
- `PlanningPhase == None`
|
|
- `BlockedByTaskId == null`
|
|
|
|
## 3. Data model (Postgres)
|
|
|
|
```
|
|
lists
|
|
id text primary key -- GUID supplied by the desktop; reuse verbatim
|
|
name text not null
|
|
updated_at timestamptz not null default now()
|
|
|
|
tasks
|
|
id text primary key -- GUID; SHARED id space (see below)
|
|
list_id text not null references lists(id) on delete cascade
|
|
title text not null
|
|
description text
|
|
imported boolean not null default false -- false = web-created, awaiting desktop pull
|
|
-- true = desktop-owned (mirrored or handed off)
|
|
created_at timestamptz not null default now()
|
|
updated_at timestamptz not null default now()
|
|
```
|
|
|
|
**Shared GUID id space.** Web-created tasks get a server-generated GUID; the desktop imports
|
|
under that SAME id, so it never duplicates. Desktop-mirrored tasks arrive with their own GUID.
|
|
All task writes are idempotent upserts keyed on id.
|
|
|
|
**`imported` flag = ownership.**
|
|
- Web `POST /tasks` inserts `imported=false`.
|
|
- Desktop pulls `imported=false`, creates the task locally (reusing the id), then `POST
|
|
/tasks/{id}/imported` flips it to `true`. From then on the task belongs to the desktop
|
|
mirror.
|
|
- `PUT /tasks/mirror` only ever inserts/updates/deletes within the `imported=true` partition.
|
|
It never touches `imported=false` rows (those are pending handoff).
|
|
|
|
## 4. Endpoints
|
|
|
|
All endpoints require a valid Zitadel access token (`Authorization: Bearer <token>`).
|
|
Missing/invalid/expired → `401`. No anonymous access (imported tasks can trigger code
|
|
execution on the user's machine).
|
|
|
|
| Method & path | Caller | Body | Response |
|
|
|---|---|---|---|
|
|
| `PUT /lists` | desktop | `[{ "id", "name" }]` — the FULL catalog | `200` |
|
|
| `GET /lists` | web | — | `200 [{ "id", "name" }]` |
|
|
| `GET /lists/{id}/tasks` | web | — | `200` tasks in that list (`404` if list unknown) |
|
|
| `POST /tasks` | web | `{ "title", "description"?, "listId" }` | `201` created task incl. `id` |
|
|
| `GET /tasks?imported=false` | desktop | — | `200 [{ "id","listId","title","description","createdAt" }]` |
|
|
| `POST /tasks/{id}/imported` | desktop | — | `200` (`404` if unknown) |
|
|
| `PUT /tasks/mirror` | desktop | `[{ "id","listId","title","description" }]` — full Idle set | `200` |
|
|
|
|
Semantics:
|
|
|
|
- **`PUT /lists`** — full replace: upsert all supplied, DELETE any list not in the payload
|
|
(cascades its tasks). Idempotent.
|
|
- **`POST /tasks`** — `listId` must exist (`400`/`404` otherwise). Server generates the id.
|
|
- **`PUT /tasks/mirror`** — full replace of the `imported=true` partition: upsert every task
|
|
in the payload (insert with `imported=true`, or update), and DELETE any `imported=true`
|
|
task whose id is not in the payload. `imported=false` rows are untouched. Idempotent.
|
|
- All task ids are client-trusted within the shared space; the server never rewrites an id.
|
|
|
|
## 5. Reconcile loop (desktop, runs each poll cycle)
|
|
|
|
```
|
|
1. PULL: GET /tasks?imported=false
|
|
for each: if no local task with that id → create local TaskEntity
|
|
{ Id = remote.id, ListId = remote.listId, Title, Description,
|
|
Status = Idle, CreatedBy = "online" }
|
|
(skip + log if remote.listId has no local list)
|
|
then POST /tasks/{id}/imported
|
|
2. PUSH LISTS: PUT /lists with the full local catalog [{id, name}]
|
|
3. PUSH TASKS: PUT /tasks/mirror with the current local Idle backlog set (§2)
|
|
```
|
|
|
|
Ordering matters: pull+import+flag first, so the just-imported tasks are part of the local
|
|
Idle set computed in step 3 and survive the mirror replace.
|
|
|
|
## 6. Minimal web client
|
|
|
|
Integrate into the existing Nuxt app at claudedo.kuns.dev if present; else a minimal page.
|
|
|
|
- Zitadel login.
|
|
- Show lists (`GET /lists`); select one to see its Idle tasks (`GET /lists/{id}/tasks`).
|
|
- Add-task form → `POST /tasks`.
|
|
- Mobile-first (main use: jotting ideas from a phone).
|
|
- **Create + read only.** No editing, reordering, status changes, or deletes.
|
|
|
|
## 7. Security
|
|
|
|
- Every route auth-gated (`401` on bad token); only static assets / login are public.
|
|
- Validate `listId` on task creation; parameterized queries only.
|
|
- CORS restricted to the web client origin.
|
|
- Don't log task titles/descriptions at info level (user content).
|
|
|
|
## 8. Deliverables from the VPS build
|
|
|
|
Report back so the desktop can be configured:
|
|
|
|
1. **API base URL.**
|
|
2. **Zitadel app/client config the desktop must use**: issuer/authority, client id, scopes,
|
|
and the OAuth flow to use for a desktop app (device-code or auth-code + PKCE), plus how
|
|
refresh tokens are issued.
|
|
3. Any env vars / README.
|
|
|
|
Out of scope server-side: task execution (the desktop runs Claude), any task state other
|
|
than the Idle mirror, multi-user / sharing / notifications.
|