# MarkEdit → General Markdown Editor: Master Plan Transform MarkEdit from a GitHub-only blog-post editor into a general-purpose markdown editor with pluggable storage connectors, a public (unauthenticated) editing experience, and a Linear-quality UI. ## Core Decisions (locked) 1. **Public editor first** — no landing page. The app opens directly into an editor. Logged-out users get multiple local documents (browser storage). To persist documents beyond the browser, users log in with ATProto. 2. **Document model** — public documents are published onto the AT Protocol; private documents stay in MarkEdit's DB and will be shareable peer-to-peer via [iroh](https://iroh.computer) (planned, not built in this phase). 3. **Connectors = ports & adapters (onion architecture)** — ATProto is just a connector, exactly like GitHub. Nothing protocol-specific lives in the core. First ATProto adapter: **PDS lexicon records only**. Tangled (git) comes later. 4. **Theme** — system-following, with both light and dark themes. 5. **Publish semantics** — all documents are saved to MarkEdit's DB first (staging). "Publish" adapts per connector rules: - ATProto (PDS records) → direct write (`putRecord` / `deleteRecord`) - GitHub → branch + commit + pull request (current behavior) - Tangled (future) → commit + push to knot 6. **Editor as a package** — the frontend editor is isolated in a package-like structure (`@markedit/editor`) from day one, so it can be published and reused in other apps later. Not feature-complete as a package yet — just structured correctly. --- ## Architecture ### Onion / ports & adapters ``` ┌────────────────────────────────────────────────────┐ │ Adapters (outer) │ │ connectors/github connectors/atproto (pds) │ │ auth/github-oauth auth/atproto-oauth │ │ share/iroh (future) │ ├────────────────────────────────────────────────────┤ │ Ports (interfaces) │ │ Connector · AuthProvider · ShareTransport │ ├────────────────────────────────────────────────────┤ │ Core (inner, dependency-free) │ │ domain: Document, Connection, Identity │ │ services: DocumentService, PublishService │ └────────────────────────────────────────────────────┘ ``` - **Core** knows about documents, drafts, connections, publish intents. It never imports a protocol SDK. - **Ports** are Go interfaces. `Connector` already exists (`internal/connectors/connector.go`) and will be extended. - **Adapters** implement ports. Each connector declares **capabilities** (`Capabilities()` → `canPullRequest`, `canDirectWrite`, `supportsFolders`, `isPublicByDefault`, ...) so the UI and publish pipeline adapt per source. ### Document-centric data model Today the app is repo/file-centric. The new core entity is the **Document**: ``` Document { id, owner_id (nullable → local/anonymous), title, content, frontmatter, visibility: public | private, binding: null | { connection_id, remote_ref, remote_sha, sync_state }, created_at, updated_at } ``` - A document may be **unbound** (scratch/local) or **bound** to a connection + remote ref (GitHub `owner/repo/path`, ATProto `at://did/collection/rkey`). - Saving always writes to MarkEdit's DB. Publishing syncs DB → remote per connector rules and records the result. ### New/changed tables (SQLite migrations) - `documents` — as above (absorbs the current drafts/pending-changes role) - `identities` — `(user_id, provider, provider_user_id, ...)` decouples users from GitHub (today `users.github_id` is the identity) - `connections` — `(user_id, connector_type, resource_ref, label, ...)` absorbs `user_repos`; one user → many connections of mixed types - `publish_log` — audit of publish events per document/connection ### Editor package layout (`@markedit/editor`) ``` frontend/packages/editor/ package.json # @markedit/editor, peerDeps: react, tiptap src/ index.ts # public API: , primitives, types components/ # SmartEditor, ClassicEditor, EditorShell, # Toolbar, FrontmatterPanel extensions/ # custom tiptap extensions built on top of starter-kit lib/ # markdown <-> doc transforms, scroll sync, etc. styles/ # editor-scoped CSS (themeable via CSS vars) types.ts ``` Contract: **no network, no app state** inside the package. Content flows in and out via props (`value`, `onChange`, `mode`, `frontmatter`, callbacks). The app (`frontend/src/`) wires it to connectors, drafts, and routing. Consumed via a local workspace dependency; publishable to npm later with no restructuring. ### Frontend app shell ``` ┌──────────────┬─────────────────────────────────────┐ │ Sidebar │ Top bar: breadcrumb · Smart|Classic │ │ (collapsible)│ toggle · save status · Publish │ │ ├─────────────────────────────────────┤ │ - connection │ │ │ switcher │ Editor (smart or classic view) │ │ - doc/file │ │ │ list │ │ └──────────────┴─────────────────────────────────────┘ ``` - Logged out: sidebar hidden; editor + local document switcher only; subtle "Sign in to save" affordance. - Logged in: sidebar appears, collapsible to a slim rail (keyboard toggle). --- ## Milestones ### M0 — Foundations: editor package + design system + app shell - [ ] Create `frontend/packages/editor/` with own `package.json` (`@markedit/editor`), entry point, and public API surface - [ ] Move TipTap editor, MenuBar, FrontmatterEditor into the package; app imports it via workspace dep - [ ] Design tokens: Inter (13px base UI / 14px editor), 1px `border-zinc-*`, 6px radius, no hard shadows; remove Archivo Black / Crimson Pro - [ ] Light + dark themes driven by CSS vars, `prefers-color-scheme` following with manual override persisted in localStorage - [ ] Replace inline SVGs/emoji with lucide-react icons (14–16px) - [ ] Restyle Toolbar (compact icon buttons), toasts, dialogs, file tree - [ ] Delete landing page: `index.astro` renders the app directly - [ ] New shell: collapsible sidebar + thin top bar (breadcrumb, view toggle, save status, Publish) ### M1 — Local documents (logged-out experience) - [ ] Multi-document scratch space persisted in IndexedDB (list, rename, delete, new doc) - [ ] Document switcher UI when logged out - [ ] "Sign in to save" flow → after ATProto login, offer to claim/migrate local docs into the account - [ ] Frontmatter editor becomes a collapsible slim panel ### M2 — Classic view - [ ] CodeMirror 6 markdown editor (left) + live preview (right) in the editor package - [ ] Draggable divider, optional scroll sync - [ ] Shared document state so Smart ⇄ Classic toggle is lossless - [ ] View-mode preference persisted per user (and locally when logged out) ### M3 — Backend onion refactor - [ ] Extend `Connector` port: write ops + `Capabilities()`; keep GitHub as first adapter, moved fully behind the interface - [ ] Connector registry/factory; per-request resolution from connection - [ ] Migrations: `documents`, `identities`, `connections`, `publish_log`; port drafts/pending-changes and `user_repos` - [ ] Re-scope API routes: `/api/connections/{id}/...`, `/api/documents/...`, `/api/documents/{id}/publish` - [ ] PublishService: dispatches per connector capability (PR vs direct write), records to `publish_log` ### M4 — ATProto auth - [ ] ATProto OAuth flow against user's PDS (handle resolution, PAR, DPoP) as an `AuthProvider` adapter alongside GitHub - [ ] Login UI offers ATProto (primary) and GitHub (for Git-backed connectors) - [ ] `identities` linking: one MarkEdit user, multiple provider identities ### M5 — ATProto PDS connector (records) - [ ] `connectors/atproto`: list/get/create/update/delete markdown records via `com.atproto.repo.*` on the user's PDS - [ ] Lexicon choice: define `app.markedit.document` (or adopt an existing community markdown lexicon — decision point before implementation) - [ ] Publish for ATProto-bound docs = direct `putRecord`; unpublish = `deleteRecord` - [ ] Public documents default to protocol publication; private stay DB-only ### Future (planned, not scheduled) - [ ] Tangled connector (git-backed; publish = commit + push to knot) - [ ] iroh-based P2P sharing for private documents - [ ] Additional connectors (generic git, WebDAV, local FS, ...) - [ ] `⌘K` command palette - [ ] Publish `@markedit/editor` to npm; extract shared editor features (collab, slash commands) into the package - [ ] Realtime collab (would live in the editor package) --- ## Open questions (resolve when the relevant milestone starts) - Exact lexicon for public markdown documents (own vs community standard) - ATProto OAuth: scopes needed (`repo:app.markedit.document` etc.) - Anonymous → authenticated document migration UX (auto-claim vs picker) - Whether logged-out classic preview rendering happens fully client-side (yes, presumably — confirm no server render endpoint is wanted)