doop - Moses Yebei

The Problem

Design teams that want to experiment with AI‑assisted graphics need a shared canvas where human edits and AI‑generated changes are visible in real time. Existing SaaS tools hide the collaboration layer behind proprietary back‑ends, making self‑hosting, data‑ownership, and custom agent integration difficult.

What This Does

doop delivers a full‑stack, self‑hostable design board that merges a React front‑end with a Node/TypeScript back‑end and an embedded Postgres (PGlite) store. The UI lives in src/ (e.g., src/components/Board.tsx, src/pages/CanvasPage.tsx) and talks to the server via REST endpoints in server/actions.ts and a WebSocket channel opened by src/lib/ws.ts.

The MCP (Multiplayer Collaboration Protocol) server in server/mcp.ts accepts connections from Claude Code or any MCP client, streams frame updates, and updates the activity feed. All persistence (frames, user accounts, agent status) is handled through the Drizzle ORM defined in server/db/ (index.ts, schema.ts, migrations under migrations/).

How It Is Wired

Entry points

Front‑end: src/main.tsx → renders <App/> (src/App.tsx).
Back‑end: server/index.ts – creates the HTTP server, mounts API routes (server/actions.ts), and upgrades /ws and /mcp to WebSocket connections.

Control flow (typical user edit)

Browser loads index.html → Vite dev server serves the React bundle.
App mounts, src/lib/api.ts creates an Axios instance targeting /api.
When a user creates or moves a frame, src/lib/api.ts POSTs to /api/frames → handled in server/actions.ts → writes via Drizzle (server/db/index.ts).
The API handler emits a broadcast through the WebSocket manager instantiated in server/index.ts.
All connected clients receive the payload via src/lib/ws.ts, which updates local React state (src/lib/store.ts) causing the canvas to re‑render.

Agent path

An MCP client (Claude Code) connects to /mcp → handshake managed in server/mcp.ts.
Agent issues set_status, create_frame, stream_content commands → routed through the same WebSocket manager.
Server validates the agent’s JWT using server/auth.ts, then persists any new frames through the same Drizzle layer.

Database All reads/writes funnel through server/db/index.ts. In dev mode it opens a PGlite file‑based DB (data/pg). Production can override with a real Postgres via the DATABASE_URL env var (referenced in drizzle.config.ts).

Docker Dockerfile builds a multi‑stage image: stage 1 compiles the Vite client, stage 2 bundles the server (server/index.ts). docker-compose.yml wires the app container to a Postgres service and exposes ports 4300 (client) and 4400 (API/WebSocket). No external services are required to start.

How To Use It

# Clone the exact repo
git clone https://github.com/moses-y/doop && cd doop

# Install deps (npm is defined in package.json)
npm ci

# Development mode (client on :4300, API/WebSocket on :4400)
npm run dev

Optional Docker route

# Generate a secret (required for auth) and start everything
BETTER_AUTH_SECRET=$(openssl rand -hex 32) docker compose up -d

Configuration lives in .env.example. At minimum set AUTH_SECRET (or the BETTER_AUTH_SECRET used above) and, for production, DATABASE_URL. The server reads these via process.env in server/index.ts and server/db/index.ts.

Real‑World Use

A product team runs doop on an internal VM, creates a canvas for a new landing page, and invites a Claude Code agent via the CLI command shown in the README:

claude mcp add --transport http doop http://localhost:4300/mcp

The agent receives the canvas ID, iteratively generates frame content, and the designers watch the updates live, comment in the activity feed, and commit the final frames to the repository.

Code Health & Issues

Low – No test coverage for server routes – only tests/access.test.ts exists; many API endpoints lack unit tests.
Low – Secrets not in CI – .github/workflows/ci.yml runs without injecting AUTH_SECRET; local dev relies on .env.example.
Low – Dockerfile copies entire repo – could be trimmed to src/ and server/ to reduce image size.

Static analysis reported no missing license (LICENSE present), lockfile (package-lock.json) present, and CI workflow exists, so baseline health is acceptable.

The Bottom Line

doop provides a functional, open‑source alternative to proprietary collaborative design tools, with a clear separation between front‑end, API, and MCP agent layers. It is ready for self‑hosting but would benefit from broader test coverage and tighter Docker image hygiene. Teams comfortable with TypeScript/Node and needing full data control should consider it; casual users may prefer the hosted version at doop.design.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

100 files

TypeScript40
TSX24
JSON6
Markdown5
YAML3
JavaScript2

ReactDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src<br/>36 modules"] g1["server<br/>23 modules"] g2["(root)<br/>4 modules"] g3["shared<br/>2 modules"] g0 -->|17| g3 g1 -->|14| g3

Module dependencies

The 10 most depended-upon modules of 66, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_shared_types["types"] n1_src_lib_store["store"] n2_src_lib_api["api"] n3_src_lib_posthog["posthog"] n4_shared_agents["agents"] n5_server_store["store"] n6_src_lib_identity["identity"] n7_server_actions["actions"] n8_src_components_AgentIcon["AgentIcon"] n9_src_App["App"] n7_server_actions --> n5_server_store n7_server_actions --> n0_shared_types n7_server_actions --> n4_shared_agents n5_server_store --> n0_shared_types n9_src_App --> n6_src_lib_identity n9_src_App --> n3_src_lib_posthog n2_src_lib_api --> n0_shared_types n2_src_lib_api --> n6_src_lib_identity n1_src_lib_store --> n0_shared_types classDef cyc stroke:#ef4444,stroke-width:2px; class n9_src_App cyc;

Dependencies

14 of 40 declared dependencies are a major version behind. Resolved 40 of 40 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^20.14.10	26.2.0	6 major
`vite`	^5.3.3	8.2.1	3 major
`@vitejs/plugin-react`	^4.3.1	6.0.5	2 major
`concurrently`	^8.2.2	10.0.5	2 major
`typescript`	^5.5.3	7.0.2	2 major
`express`	^4.19.2	5.2.1	1 major
`nanoid`	^5.0.7	6.0.1	1 major
`react`	^18.3.1	19.2.8	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium7

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

contributor-assistant/github-action@v2.6.1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:22-slim, node:22-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Expand the test suite; it cannot cover this codebasemedium

1 test files against 66 source files (ratio 0.015)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.