Documateo — The Bible 🚀
Your single source of truth: build, security, no-bug discipline, growth from 1 week to 5 years, marketing and business. Rebuilt from the live site (documateo.com, crawled fresh), the actual codebase, and the vision doc's own 19 Jul 2026 baseline audit — cross-checked against what's shipped since.
🧭 How to use this tracker
This file is self-contained — no login, no cloud dependency. Everything lives in your browser, with backup/restore to keep it safe across devices.
1
Navigate with the sidebar — grouped by System Map, Product Pillars, Platform Operations, Security/QA, Growth Timeline, and Marketing/Business.
2
Click any task to mark it done (turns green ✓). Click again to unmark.
3
Growth Timeline has horizon tabs — 1 Week, 1 Month, 3/6/12 Months, 2–5 Years — each with its own focus and checklist.
4
Press "💾 Save Progress" (or Ctrl+S) — saves to browser localStorage. Progress persists between sessions.
5
Use "⬇ Backup / Restore" to download a .json file regularly. Re-import on any device to sync progress — treat this like a save file.
Tasks Done
0
of 0 total tracked tasks
Overall Progress
0%
Across every pillar
Current Phase
Phase 0
Stabilize & De-Risk
Tools Live
58 / 62
30 PDF · 20 Image · 4 Video · 4 Utility, 4 stubs left
Loading…0%
🎯 Today's Mission
Loading…
💸 AI Spend (month)$0
❤️ Platform Health—
🚦 Release Ready0 / 4
🔐 Critical Security Closed0 / 0
🕓 Recent Activity
- No activity yet — tick a task to get started.
The honest position, restated: the vision doc's own baseline audit (19 Jul 2026) flagged Protect/Unlock PDF as "registered but broken" — a real bug someone could click into and fail on. That's fixed now, and fixed well: a dedicated pdf-crypto container running native qpdf, not the WASM path the doc suggested, because shipping a large WASM bundle to every visitor for a tool most won't use was the wrong tradeoff. Domain and pricing risks are also resolved. What's genuinely still open: zero production monitoring, a silent failed-payment email gap, and flat (unweighted) per-tool credit costs.
✅ Shipped Since the 19 Jul Baseline — Verified From Code
- Protect/Unlock PDF fixed via a dedicated pdf-crypto container (native qpdf, real AES-256) — tools.ts now correctly lists both as engine:"container", not the broken browser path.
- Domain unified to documateo.com everywhere (metadataBase, sitemap, robots, OAuth redirect) — confirmed live via Google's own index.
- Pricing moved off a hardcoded "EDIT BEFORE GOING LIVE" placeholder into an admin-editable pricing_config D1 table, seeded with real, dated numbers (matched to iLovePDF's confirmed-live $9/mo).
- 10 of the original 14 stub tools shipped: Extract Text, PDF Info, Remove Metadata, Add Text, Stamp, Flatten, Scan to PDF, Batch Processing, Bulk Resize, Aspect Crop. Only 4 remain.
- Two-role admin RBAC (support/super_admin) with a second-factor admin-panel secret and its own attempt-tracking table.
- Per-account login lockout on top of per-IP rate limiting — closes a real credential-stuffing gap.
- Real-time job progress percent for video jobs (ffmpeg -progress pipe), correctly NULL (not faked) for containers that can't report it.
- Invoice system with GST-ready template, correctly showing 0% until the registration flag flips — no retroactive risk.
📐 The Core Question
Before building any new feature: is this genuinely new capability, or does the infrastructure already exist and just need wiring? Extract Audio from Video is the clearest example — the ffmpeg container it needs is already deployed and running 4 other video tools.
Documateo
│
├── Core (auth, domain unified, D1/R2/KV — DONE)
├── PDF Tools (30/30 — Protect/Unlock fixed via container — DONE)
├── Image Tools (20/20 — DONE)
├── Video Tools (4/5 — Extract Audio stub, infra exists — MOSTLY DONE)
├── Utility Tools (4/4 — DONE)
├── Containers (4 images: video, office, pdf-repair, pdf-crypto — DONE)
├── Billing (pricing now real + admin-editable — MOSTLY DONE)
├── Admin Console (2-role RBAC, refunds, discounts — DONE)
├── Job Lifecycle (queues, DLQ, cron sweep, progress — DONE)
├── Marketing Site (69 posts, sitemap, category pages — MOSTLY DONE)
│
└── Monitoring (Sentry/PostHog) — NOT WIRED, still invisible
└── highest-priority open item on the whole platform
North Star & Strategy
The strategic frame every other decision in this tracker hangs off of.
🧭 The Strategic Shift
Documateo wins on speed, privacy, and honesty about limits — not tool count.
72% of tools run 100% client-side — the file never leaves the device. That's a genuine, technically-true claim none of iLovePDF, Smallpdf, or Sejda can make across their whole catalog. The 3-year north star: documateo.com ranks above ilovepdf.com for 15+ of the highest-volume tool keywords (merge pdf, compress pdf, pdf to word) in India first, then global English-speaking markets — profitable on pay-per-use, never requiring venture funding.
⚠️ The Open Question This Tracker Answers
The vision doc's own baseline audit is dated 19 Jul 2026 — the code has moved substantially since. Its #1 flagged bug (Protect/Unlock PDF broken) is fixed, and fixed with a better solution than the doc itself proposed. Its #1 flagged domain risk is resolved. Its placeholder-pricing risk is resolved. What genuinely remains open — zero monitoring, a silent failed-payment email gap, flat per-tool credit costs — is now precisely scoped instead of buried under fixed items. Treat this tracker as current; treat the vision doc as historical baseline.
📊 Wrong Metric vs Correct Metric
Track outcomes, not activity. A signed-in heavy-tool job or a blog post that actually drives tool usage is the real unit of value.
| Instead of tracking | Track this | Why it matters |
|---|---|---|
| Total tool uses | Container/AI tool uses by signed-in vs. anonymous users | Anonymous heavy-tool credits are a real, currently-untracked cost |
| Signups | Signups who complete a 2nd heavy-tool job in the same week | One-and-done anonymous usage never becomes a customer relationship |
| Blog traffic | Blog → tool page click-through, by post | 69 posts exist; knowing which drive tool usage tells you what to write more of |
| — | Real cost-per-job vs. credits_charged, by tool | tool_credit_costs is seeded flat at 1 — this is the data needed to fix that |
| — | payment.failed → recovery rate once the missing email is built | Currently 0%, because no email fires — a real, fixable leak |
🏷️ Revenue Model — Real Numbers, Admin-Editable
pricing_config (D1, migration 0006) replaced the hardcoded "EDIT BEFORE GOING LIVE" placeholder. The ₹699/mo number is unchanged but now deliberate — matched to iLovePDF's real, confirmed-live $9/mo, not guessed.
| Tier | Access | Price (INR) | Price (USD) |
|---|---|---|---|
| Free | All 58 tools; 72% unlimited forever; heavy tools on a daily anonymous credit allowance | ₹0 | $0 |
| Pro | 60 credits/mo for container/AI tools | ₹699/mo · ₹5,999/yr | $9/mo · $60/yr |
| Business | 300 credits/mo, ~2.86× Pro ratio | ₹1,999/mo · ₹17,999/yr | $25/mo · $170/yr |
Guiding Principles
Every architectural and pricing decision should comply. Re-read before any sprint that touches more than one tool category.
Standing rule for every decision: if a system could be reused across PDF/Image/Video/Utility tools, it belongs in Core. If it's specific to one tool's logic, it lives in that tool's own engine file.
1
No leaking money — requirePlan.ts has no bypass path, ever
Every container/AI job is gated. No "free trial" feature, referral bonus, or admin override skips this without being logged and capped.
2
Browser-first stays free forever
The 72% client-side tools cost nothing to run and must never be paywalled, rate-limited by plan, or degraded to push upgrades. This is the core brand promise, not a feature.
3
No stale URLs — a stub, never a 404, never a silent redirect
Every V1 URL either has a real tool or a ToolNotYetAvailable stub. SEO equity is never dropped silently.
4
A registered-but-broken tool is worse than an honest stub
The Protect/Unlock PDF incident — listed as shipped, actually threw on every call — is the direct lesson. Never mark a tool live in tools.ts until it genuinely works end-to-end.
5
One source of truth per concern
Tool metadata lives only in tools.ts. Pricing lives only in pricing_config. Extend this pattern to every new subsystem — no hardcoded prices, no duplicated tool lists in the frontend.
6
Don't force WASM if it visibly degrades output quality
The pdf-crypto container is this principle applied correctly — a native qpdf binary server-side beats a large WASM bundle shipped to every visitor for a tool most won't use. Cost-cutting never wins over a broken output.
7
Ship reversible, not risky
Prefer feature flags (FEATURE_FLAGS KV, platform_settings kill switches) over big-bang cutovers. Anything touching money or auth ships behind a flag with a kill switch.
8
A schema migration should not silently change behavior on deploy day
tool_credit_costs was seeded flat at 1 specifically to avoid repricing anyone the moment it shipped. Weighting is now possible, applying it is a deliberate follow-up decision, not a side effect.
9
No task is "done" because code exists
It's done when it's deployed, tested, and verified against the money firewall and mobile viewport. This applies to this tracker's own checkmarks too.
10
Radical honesty about what's local vs. server-side is the actual product
"This file never leaves your device" or "deleted within 2 hours" — stated plainly on every tool page. This is differentiation, not a privacy-policy footnote.
All Systems
Every internal system across Documateo. Status, maturity, and dependencies — auto-tracked from your checklists, the rest editable inline.
Identity, Domain & Core
One login system, one canonical domain, D1/R2/KV storage — the foundation every tool category depends on.
Confirmed live: email+password, email verification, password reset, magic link, Google OAuth, session cookies. documateo.com is the single canonical domain everywhere — the vision doc's top Phase 0 risk (two domains in one codebase) is resolved.
🔐 Identity & Authentication
Email+password, email verification, password reset, magic link, Google OAuth
Session cookies, KV-cached for fast edge reads
Per-account login lockout on top of per-IP rate limiting (migration 0012)
🌐 Domain Strategy
documateo.com unified everywhere — metadataBase, sitemap, robots, OAuth redirect
Old appv2/apiv2 domains 301 cleanly if any traffic still hits them
🗄️ Storage & Config
D1 schema — 13 migrations applied, users/jobs/pricing_config/tool_credit_costs and more
R2 buckets (uploads/outputs) + KV (rate limits, session cache, feature flags)
R2 2-hour lifecycle rule confirmed live via CLI/screenshot, not just documented
Critical Build Order
The spine of the platform. Build top to bottom — each layer unlocks the next. Support modules run in parallel alongside it.
🪜 The Spine
🔧 Support Modules (parallel, non-blocking)
Impact & Priority
Score every system on Business Value, Engineering Effort, Reuse, Risk, and Strategic Fit. Click a star to re-rate — it's saved instantly.
📄 PDF Tools ✓ 30/30 Live
The largest, most mature category. Includes the Phase 0 fix: Protect/Unlock PDF now run on a dedicated pdf-crypto container.
Uses These Systems
📄 Core PDF Editing — Browser/pdf-lib
Merge, Split, Rotate, Watermark, Organize/Reorder, Delete Pages, Add Page Numbers, Crop — all pdf-lib, pure browser
Image to PDF — pdf-lib + native Canvas composition
Extract Text, PDF Info, Remove Metadata — shipped since the 19 Jul baseline
Add Text to PDF, Stamp PDF — same overlay pattern as Watermark, shipped since baseline
Flatten PDF (form flattening), Scan to PDF (Canvas capture) — shipped since baseline
Batch PDF Processing — client orchestration of existing browser tools, shipped, doubles as the foundation for tool chaining
🔒 Protect / Unlock — Fixed via Container
Protect PDF (add password) — pdf-crypto container, native qpdf, real AES-256
Unlock PDF (remove known password) — same container, same fix
📦 Container/AI-Backed PDF Tools
Compress PDF (mupdf-wasm, routes >25MB server-side), PDF to JPG/PNG, Extract Images from PDF
Repair PDF (qpdf/mutool container), HTML to PDF (Browser Rendering API), PDF to Word/PPT/Excel, Office to PDF (LibreOffice), PDF to PDF/A, OCR PDF
🚧 Remaining for This Pillar
Redact PDF — visual black-box only until content-stream-level removal is verified; never ship a "permanent" claim until true
PDF to Excel returns Markdown tables, not real .xlsx — known quality gap flagged directly in tools.ts comments
🖼️ Image Tools ✓ 20/20 Live
Mostly pure browser via WASM codecs (jsquash). remove-bg and upscale on Cloudflare Images/Workers AI.
Uses These Systems
🖼️ Browser-Native Tools
Compress (jsquash), Resize (pica), Crop, Convert (JPG/PNG/WebP/BMP) — all pure browser
Watermark, Rotate & Flip, Grayscale/B&W, Circle/Shape Crop — Canvas API
EXIF viewer + remover — privacy-critical: strips GPS data client-side, never reaches a server
Merge Images (collage), GIF Maker, GIF to Images (extract frames), Add Text/Meme tool
Brightness/Contrast/Color adjust — WebGL shader for real-time preview
HEIC to JPG — libheif-wasm, common enough (iPhone photos) to justify dedicated WASM
Bulk Resize (multi-file extension of existing resize.ts), Aspect Ratio Crop — shipped since baseline
🤖 AI-Backed Tools
Remove Background, Image Upscaler — Cloudflare Images / Workers AI, genuinely need a trained model
🎬 Video Tools 4/5 Live
Entirely container-backed via ffmpeg — WASM would OOM on mobile for anything over ~30s of 1080p, so this category deliberately never went client-side.
Uses These Systems
🎬 Live Tools
Compress Video — ffmpeg container
Convert Video (MP4/WebM/MOV) — ffmpeg container
Video to GIF — ffmpeg frame extraction + palette optimization
Trim/Cut Video — hybrid: instant client-side preview (MediaSource API), server-side does the real encode
🚧 Remaining
Extract Audio from Video — the ffmpeg container it needs is already deployed, one of the lowest-effort remaining stubs
🧰 Utility Tools ✓ 4/4 Live
Pure browser, zero server cost, zero monetization pressure — QR, password, hash, ZIP.
🧰 Coverage
QR Code Generator — pure JS (qrcode)
Password Generator — Web Crypto API (crypto.getRandomValues), never server-side, full stop
File Hash Generator — SHA family native Web Crypto, MD5 via small JS lib
Create/Extract ZIP — fflate, handles GB-scale zips client-side with streaming
📦 Cloudflare Containers ✓ 4 Images Deployed
Native binaries, scale-to-zero, per-second billing — not a VPS. Real .workers.dev URLs live for all 4 images.
Why containers instead of "a VPS": no idle cost, no OS patching, no SSH surface — Cloudflare manages the runtime. A 12-second video compress costs ~12 seconds of compute, not a slice of a $20/month server.
📦 The 4 Images
video — ffmpeg, powers Compress/Convert/Video-to-GIF/Trim-export
office — LibreOffice headless, powers PDF↔Word/PPT/Excel/Office-to-PDF
pdf-repair — qpdf/mutool, powers Repair PDF for genuinely corrupted files
pdf-crypto — qpdf, powers Protect/Unlock PDF, built after the vision doc baseline specifically to fix the broken-tool incident
🛡️ Container Security Posture
Read-only rootfs, no outbound network, ephemeral, auto-destroyed after job — confirmed across all 4 Dockerfiles
Cold-start latency (sleepAfter: "1m") load-tested under real traffic, not just dev
🤖 AI Product Line Early — 2 Wired, Chat-with-PDF Pending
Workers AI for OCR and PDF→Excel table detection, Cloudflare Images for remove-bg/upscale. Ask AI About a PDF is the seed of a real product surface, not a throwaway.
🤖 Live Today
OCR PDF — Cloudflare Workers AI, pay-per-page, zero idle cost
PDF to Excel table detection — toMarkdown(), known limitation: returns Markdown not real .xlsx
🚧 The Real Build Ahead
Ask AI About a PDF — needs its own persistent-chat UX pattern, not the standard AsyncToolShell; the seed of Phase 6's whole AI product line
💳 Billing & Monetization
Razorpay, prepaid-pass model — a deliberate divergence from the original architecture doc's generic credit/subscription hybrid, chosen specifically to avoid recurring-payment webhook fragility.
💳 Core Billing ✓ Live
Razorpay prepaid-pass flow — order-based, not recurring subscription
Webhook idempotency — Razorpay event ID dedup in D1, survives retries safely
pricing_config D1 table — replaced the hardcoded "EDIT BEFORE GOING LIVE" placeholder, admin-editable, no redeploy needed
tool_credit_costs table — makes per-tool cost-accurate credit weighting possible (migration 0006)
GST-ready billing_settings + invoice system — 0% shown correctly until registration flag flips, zero retroactive risk
Admin refund tool
🚧 Remaining
RAZORPAY_WEBHOOK_SECRET verified actually SET in production — code reads it correctly, but this is a deployment fact no source read can confirm
Failed-payment recovery email — payment.failed webhook updates D1 status but never calls the email service, confirmed by direct code read
Golden Rule — reconfirmed: requirePlan.ts hard-blocks anonymous/free users from ever reaching container/AI cost, no bypass path. Every new heavy-tool route inherits this scrutiny by default — verify it explicitly on each one anyway.
🛠️ Admin Console ✓ Live
Overview, users, passes, refunds, discount codes. Two-role RBAC layered carefully on the original coarse is_admin flag.
🎛️ Coverage
Admin routes require session.isAdmin at the mount point — one choke point, not scattered per-route checks
Two-role split — support (day-to-day refunds/discounts/lookups) vs super_admin (pricing, credit costs, GST, promoting other admins)
Second-factor admin-panel secret with its own attempt-tracking table (admin_secret_attempts)
User management — view/search/suspend, cascading effects on passes/jobs
Refund tool wired to Razorpay's real refund API, not just a DB status flip
Discount code management, platform_settings kill switches (3 independent switches, correctly scoped)
🚧 Remaining
Discount code max-redemption-count and expiry field confirmed in schema (0005), not assumed
⚙️ Job Lifecycle ✓ Live
Queues + DLQ + hourly cron sweep. Real-time progress percent for video, correctly NULL for containers that can't report it.
⚙️ Coverage
jobs-container, jobs-ai, jobs-cleanup, jobs-dlq queues — 3-retry then alert + auto-refund
Hourly cron sweep — expired jobs, orphaned stuck jobs, expired passes
No credit charged before a job is confirmed queued — verified order of operations in routes/jobs.ts
Real-time progress_percent for video jobs (ffmpeg -progress pipe), NULL correctly for office/repair/crypto
Container callback authenticated with CONTAINER_CALLBACK_SECRET, not a user session — correct trust boundary
🌐 Marketing Site & SEO
Static sitemap.xml, robots.ts, 69 blog posts, category landing pages, FAQ/legal pages.
🏠 Core Pages ✓ Live
Homepage, pricing, about, FAQ, legal pages
69 blog posts live
Category landing pages — PDF/Image/Video/Utilities
Static sitemap.xml + robots.ts, aligned to the single documateo.com domain
58 tool pages confirmed matching tools.ts exactly — verified against the live site's own "58 tools, 72% local" claim
/developers and /status pages live per the site footer
🚧 Remaining
/vs/ilovepdf, /vs/smallpdf, /vs/sejda comparison pages — factual, evenhanded, competitor pricing sourced and dated
Per-tool "how it works" trust block on every tool page — "never leaves your device" vs "deleted within 2 hours"
🔌 API Platform Early — /developers Live, Public API Not Started
Targets the pdf.co segment. Today's API is session-auth only, consumed by the web app itself.
🔌 Coverage
/developers page exists per the site footer
🚧 Genuinely Not Started
API-key auth layer alongside existing session auth on the same Worker routes
Per-API-key rate limiting, usage-based billing — evaluate Stripe for a USD-default developer audience
🔐 Security Checklist
Categorized, severity-tagged, grounded in the actual codebase — including the untrusted-file handling discipline that makes 4 native-binary containers safe to run.
The platform's #1 named gap: zero production monitoring. No Sentry, PostHog, or Analytics Engine found anywhere — a production error, including a failed payment or a crashed container job, is currently invisible until a user reports it manually.
✅ No-Bug / QA Policy
The discipline that keeps production clean. Adopt these as standing practice, not a one-time checklist.
The bar: a tool is never registered as shipped in tools.ts until it genuinely works end-to-end. The Protect/Unlock PDF incident — listed live, actually throwing on every call — is the direct lesson: a registered-but-broken tool is worse than an honest stub.
⏳ Growth Timeline — 1 Week → 5 Years
Every horizon has its own focus and checklist. Switch tabs to zoom in or out on the plan.
Phase Roadmap (0–7)
Reconciled against the actual codebase, which has moved substantially since the vision doc's 19 Jul 2026 baseline. Click a phase to expand.
🛰️ Future Modules
Phase 4-7 from the vision doc. Not yet built — sequence by real demand signal.
📋 Tracked Tasks
Client-side tool chaining — "compress then watermark" as a saved pipeline, zero new infra
Job history at /account/history — confirm wired to real data, not a placeholder
Drag-and-drop multi-tool dashboard
Keyboard shortcuts + power-user mode
Multi-region D1 read replicas — once traffic outside India grows meaningfully
Desktop app (Tauri) — reuses the same WASM engines already built
Browser extension for quick-access tools
📣 Marketing Channels
How to play reachability — owned content, product-led growth, community, partnerships, and paid (only after real unit economics are validated).
✅ Marketing Action Checklist
🔍 SEO Playbook
Technical foundation, keyword strategy, link building, and measurement.
✅ SEO Action Checklist
💼 Business & Revenue
Pricing, unit economics, retention — grounded in the real, now-admin-editable pricing_config model.
💳 Plan Tiers
✅ Business Action Checklist
Ownership Matrix
The most important document. Before building any feature — check this first.
The core question: could more than one tool category (PDF, Image, Video, Utility) reuse this in the next 12 months? YES → Build in Core. NO → Build inside that category's own engine.
Feature Ownership
| Feature | Owner | Location | Notes |
|---|---|---|---|
| Authentication | Core | apps/api/src/routes/auth.ts | Every tool category imports this |
| Pricing | Core | lib/pricing.ts + pricing_config table | Single source of truth since migration 0006, admin-editable |
| Tool registry | Core | packages/tool-config/src/tools.ts | getToolByPath() is the ONLY sanctioned URL→tool lookup — never match on slug directly in routing code |
| File validation (magic-byte, zip-bomb, size cap) | Core | middleware/fileValidation.ts | Runs on every upload regardless of tool category |
| requirePlan.ts money firewall | Core | apps/api/src | The single enforcement point for the golden rule — no bypass path |
| PDF engines (pdf-lib, mupdf-wasm) | PDF Tools | lib/engines/browser/pdf/ | Category-specific |
| pdf-crypto container | PDF Tools | apps/workers-containers/pdf-crypto | Built specifically for Protect/Unlock, not reused elsewhere |
| Image codecs (jsquash, pica) | Image Tools | lib/engines/browser/image/ | Category-specific |
| ffmpeg container | Video Tools | apps/workers-containers/video | Powers all 5 video tools including the pending Extract Audio |
| Job queue + DLQ | Core (Jobs) | routes/jobs.ts + queue consumers | Shared across container/AI tools from any category |
Cross-Pillar Matrix
Which tool categories consume which internal systems — and how built-out each pairing already is.
🚫 Kill List
Do NOT build any of these before real demand signal. Re-read this before every sprint.
If you find yourself about to build one of these: stop, re-read the Guiding Principles, and ask if there's a simpler path.
Tech Stack
Confirmed choices from the actual codebase.
⚠️ Risk Register
Named risks with their mitigation — revisit quarterly.
AI Cost Dashboard
Track Workers AI (OCR, PDF→Excel) and Cloudflare Images (remove-bg, upscale) spend against the golden rule.
Platform Health
A weighted self-assessment across the dimensions that actually predict production pain. Adjust sliders as things change.
Release Readiness
A category is marked "Ready" only when its overall score is ≥85%, testing ≥70%, and docs ≥50%. No exceptions.
Technical Debt
Real, named gaps — plus any new shortcuts you take on purpose. Log them here so they get paid down deliberately.
Title
Severity
Est. hours
Decisions Log
Lightweight Architecture Decision Records. Capture the why, not just the what.
Decision
Reason
Alternatives considered
My Notes
Free-form workspace. What you're building today, blockers, ideas.
Current Focus
Blockers
Next 3 Actions
Decisions Made (free-form)
Open Questions
Abandoned / Deprioritized
Ideas Backlog