Subcanvas
Turn a GitHub repo into a diagram you can click into. Paste a GitHub repository, public or private, and each main folder becomes a box with its README inside; a box opens into the folders within it. Then draw the rest: any box or arrow can hold its own whiteboard or a page of notes, as many levels deep as you need.
This repository's own diagram, drawn live by subcanvas.app from its folders and .subcanvas files. Click it to open the boxes.
- GitHub import. A box for each main folder (up to 60), with its README inside. A
.subcanvas file in a folder says what it is and what it talks to, and those connections become arrows. Private repositories come in read-only once the workspace connects GitHub in Settings, and always as private projects. The import is a one-time copy.
- Code links. A box or an arrow can point at the code behind it, a file, some lines or a folder on GitHub or anywhere else, and one click opens it. Imported boxes link to their folders.
- Nesting. Double-click a box or an arrow to open the whiteboard or page inside it. A trail of tabs shows where you are and leads back out.
- Live together. Invite people to your workspace and everyone edits at once, with cursors. Viewers are free.
- README embeds. A public whiteboard embeds as a picture that follows your edits within minutes and links to the live version.
- Agents. An MCP server lets Claude Code, Codex, Cursor and other agents read and edit as the person who connected them, and a Claude Code plugin teaches them to draw: Agents below.
- Your notes. Notion, Obsidian, Google Docs and folders of Markdown come in through Import files: docs/IMPORTING.md.
- Mermaid. Paste a Mermaid flowchart, sequence diagram or ER diagram, or have an agent send one, and it becomes a whiteboard of real boxes and arrows you can click into and edit: docs/IMPORTING.md.
- Your work, out. A page downloads as Markdown and a whiteboard as SVG from its menu, and a whole project exports as a zip of those, with a JSON file of each whiteboard and its pictures and videos. Import files brings the zip's pages back: docs/EXPORTING.md.
Subcanvas is live at subcanvas.app and changing fast. What is being built is in REQUIREMENTS.md, the data model and build order in docs/ARCHITECTURE.md, and what comes next in docs/ROADMAP.md.
Agents
An agent connected to Subcanvas reads and edits it as you, with your role in each workspace. For Claude Code, install the Subcanvas plugin: it adds the server at subcanvas.app and a skill for drawing whiteboards people can read, with boxes that open into their own whiteboards and a page behind each arrow.
claude plugin marketplace add subcanvas/subcanvas
claude plugin install subcanvas@subcanvas
Then type /mcp in Claude Code and sign in. Every other client, and a server of your own, is in docs/MCP.md; the plugin is in plugins/subcanvas.
What to ask your agent
- Map this repository's services and how they talk to each other as a Subcanvas whiteboard, then put a page behind each arrow saying what crosses it.
- Explain this pull request as a Subcanvas whiteboard: a box for each part it changes, arrows for how the changes depend on each other, and a page inside each box saying what changed and why.
- Turn docs/onboarding.md into a nested Subcanvas whiteboard: a box for each section, with its detail on a page or a whiteboard inside the box.
- Keep the Subcanvas diagram of this repository up to date with this branch. Add what the branch adds, fix what it changes, and ask me before you remove anything.
- Review the Architecture whiteboard in Subcanvas against the code and fix what is wrong. List anything you would delete and wait for my answer.
Stack
Next.js · Supabase (Auth, Postgres, Realtime, Storage) · React Flow · BlockNote · Yjs · shadcn/ui · Stripe
Subcanvas stands on open source work, with thanks: the whiteboard canvas is React Flow by xyflow (MIT), laid out with dagre (MIT); pages are BlockNote (MPL-2.0); live collaboration is Yjs (MIT); the interface is built from shadcn/ui and Base UI (MIT) with Lucide icons (ISC). The canvas does not show React Flow's attribution badge, which its license allows; this paragraph is where the credit lives instead.
Development
Requires Node 22+, pnpm, Docker, and the Supabase CLI.
pnpm install
supabase start # local Supabase stack; prints the API URL and keys
cp .env.example .env.local # then paste in the publishable key
pnpm dev
| Command | What it does |
|---|
pnpm dev | Start the app at http://localhost:3000 |
pnpm lint | ESLint |
pnpm typecheck | TypeScript, no emit |
pnpm build | Production build |
pnpm test | Unit tests (Vitest) for code that needs no browser and no database |
pnpm test:e2e | End-to-end tests (Playwright) in a real browser against a real build |
pnpm db:test | Database tests (pgTAP), including row-level security |
pnpm db:types | Regenerate src/lib/supabase/database.types.ts after a migration |
supabase db reset | Rebuild the local database from supabase/migrations |
Sign-in is by email and password or by an emailed link. Locally, emails are caught by Mailpit at http://127.0.0.1:54324 instead of being sent. Google and GitHub sign-in are off by default; see the notes at the bottom of supabase/config.toml.
After changing supabase/config.toml, restart the stack with supabase stop && supabase start.
Tests
Three layers, each answering something the others cannot:
pnpm test: Vitest, over code that needs no browser and no database. It is the one that runs in a second, so keep it that way: nothing here may start a server.pnpm db:test: pgTAP, over the migrations. Row-level security is the real permission system, and this is where it is proved.pnpm test:e2e: Playwright, in e2e/. A browser signs up, makes a project and a whiteboard, draws on it, reloads, and looks again: the only check that sees a Yjs document reach Postgres and come back. It also reads a public project with no account at all.
The end-to-end suite needs the local stack (supabase start) and builds the app before it serves it, on port 3310, so it never fights a pnpm dev on 3000. Every spec makes its own account, workspace and project, named after a fresh id, so the specs run in any order, run in parallel, and leave a shared database alone: nothing is deleted. Sign-in links are read back out of Mailpit, the same inbox a person developing here would open, and so are the app's own emails, invites, abuse reports and what it tells the operator, which .env.example sends to Mailpit's SMTP port; the specs that read those skip when SMTP_HOST is not set, and the one that sends the daily summary skips without CRON_SECRET. One spec, github-import, runs against a second, development server (port 3410, or E2E_DEV_PORT) started with SUBCANVAS_IMPORT_FIXTURES pointing at e2e/fixtures/github: "Import from GitHub" reads a repository that is a folder there, so no test asks api.github.com for anything. Next refuses a second development server in one checkout, so with pnpm dev already open, start that one from another checkout of the repository (a git worktree will do) and point the suite at it with E2E_DEV_BASE_URL. The billing specs pay through Stripe's sandbox and start the Stripe CLI, so they run only when asked for with E2E_BILLING=1 and STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are set (sandbox values, see Plans and billing below), and skip otherwise. The specs in which an agent signs in, and those of the Connect an agent page, need [auth.oauth_server] from config.toml, which a stack started before that setting only picks up after supabase stop && supabase start; without it they skip, and one that checks a server without agent sign-in runs instead. Specs whose pages depend on the server's setup (billing, NEXT_PUBLIC_AUTH_PROVIDERS) read it from the environment or .env.local, as the server does.
pnpm test:e2e # all of it
pnpm test:e2e whiteboard-node # one spec
E2E_DEV_BASE_URL=http://localhost:3410 pnpm test:e2e # with a fixture server you started yourself
pnpm exec playwright test --ui # watch it happen
pnpm exec playwright show-report # the last run, in detail
Prefer accessible names (getByRole, getByLabel) to class names, and a web assertion to a sleep. Do not dispatch synthetic mouse events at whiteboard nodes: React Flow hands them to d3-drag, which reads event.view.document and throws. Move and press the real mouse, or use the + menu.
Public projects and moderation
An admin or owner can make a project public, when creating it or later: anyone with the link can then read every document in it, and nobody outside the workspace can edit. The link is the project's own address (/<workspace>/<project>), the one its members use, and each whiteboard and page in it has one too (/<workspace>/<project>/<title>-<code>). Public pages are not indexed by search engines, and each carries a Report button.
Reports land in the abuse_reports table, readable only by the operator (the Supabase dashboard or SQL), and are emailed to ABUSE_EMAIL (or LEGAL_CONTACT) when the server sends email. To take a project offline, whatever its workspace sets:
update public.projects set taken_down_at = now() where id = '<project id>';
Its members then see that it was taken down and whom to write to. Reviewing reports, reversing a takedown, and deleting an account by hand are in docs/OPERATIONS.md.
Embedding a diagram
Whiteboards take pictures and videos: drop files on the canvas, paste a screenshot, or choose Picture or video from the + menu, and point arrows at them like at any other node (PNG, JPEG, WebP, GIF, AVIF up to 10 MB; MP4, WebM, MOV up to 100 MB).
Paste a link on a whiteboard and it becomes a card: the page's title, a line of its description, its site and its picture, read once when you paste it and kept with the whiteboard, so nobody who looks at the card later loads anything from the page's site. A YouTube link plays on the card once you press play, through YouTube's no-cookie player. Double-click a card, or use its corner mark, to open the page.
Any whiteboard in a public project is also served as a picture at /p/<project id>/d/<document id>/embed.svg (add ?theme=dark for the dark version). On the whiteboard's page, Share has Copy embed, which copies a snippet for a README or a docs site: the picture, in the reader's light or dark theme, linked to the live whiteboard. The picture is drawn from the whiteboard on request, so it follows edits within a few minutes with no change to the README. A whiteboard that is private, in the trash, or missing gets a picture that says so. Pictures and videos on the whiteboard show in the embed as captioned frames: the embed is one standalone image and never loads another file.
Plans and billing
Billing is off by default, and a self-hosted server needs none of it: with nothing configured there are no limits, no Billing page, and the Stripe code never runs.
A deployment that sells subscriptions turns on two things:
- The free plan's limits, enforced in the database:
update private.config set free_private_document_limit = 100, free_editor_limit = 1;
Free workspaces then get unlimited documents in public projects, 100 documents across private projects (the descriptions of boxes and arrows do not count, nor does anything in the trash or inside something that is), and 1 editor. Viewers are always unlimited and free. A workspace on the paid plan, Pro, has no limit on documents or editors. Storage for pictures and videos has a cap of its own for each plan, off unless set (free_media_storage_limit_bytes and paid_media_storage_limit_bytes; subcanvas.app gives 1 GB free and 100 GB on Pro).
- Stripe. Set the Stripe variables in
.env.example, using a recurring $5 per-editor price. In production, point a Stripe webhook at /api/stripe/webhook with the customer.subscription.* and checkout.session.completed events. Locally, run pnpm stripe:listen instead, and keep it running while you test: it forwards the sandbox's events to your dev server, and the signing secret it prints on first run is your local STRIPE_WEBHOOK_SECRET. Use a sandbox secret key, never a live one, in .env.local.
Contributing and security
Bug reports and ideas are welcome as issues; code contributions are not accepted yet: see CONTRIBUTING.md. To report a security problem, email [email protected] (SECURITY.md).
License
Copyright (C) 2026 Trevin Lee
Subcanvas is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, version 3.
In short: you may self-host and modify it, but if you run a modified version as a network service, you must make your modified source available to its users. It comes with no warranty.
