Skip to main content

​
Summary

Two milestones on the Choco documentation platform (cho.co): full mock document navigation is now working end-to-end, and Clerk auth has been completely removed with BetterAuth stubs in place.

​
What changed

​
Mock document navigation (shipped)

Users can now click through the entire document workflow: factory floor plan → room → document list → document detail → editor. 16 realistic technical documents are spread across all 7 factory rooms, covering topics like CRDT synchronisation, WebSocket protocols, CLI quickstarts, and audit ledger architecture. Documents have mixed verification states (verified, pending, failed) matching real platform behaviour.

​
Clerk removal (shipped)

The Clerk authentication provider has been fully removed from the codebase. 10 source files were updated, 14 npm packages removed. Sign-in and sign-up pages now show BetterAuth placeholder UI. The middleware, API client, and configuration files are all clean and ready for BetterAuth integration.

​
Key findings with business impact

​
Auth migration was zero-risk because of prior preparation

All Clerk usage was already wrapped in conditional checks (hasClerkKey). The platform had been running without Clerk credentials for weeks with no issues. This meant the “removal” was deleting dead code, not disconnecting a live service. No user-facing disruption, no rollback risk. Takeaway: When migrating auth providers (or any critical dependency), wrapping the old provider in feature flags first and shipping without it for a cycle is the safest path. This pattern should be standard for future provider swaps.

​
The document editor component existed but was never connected

The TiptapEditor component — a rich text editor with a full toolbar — was built and sitting in the codebase but never actually rendered on the edit page. The page showed a “loading” placeholder instead. This was discovered while wiring mock data through the navigation flow. Takeaway: End-to-end navigation testing catches dead code and missing integrations that component-level reviews miss. The mock data layer is paying for itself as a QA tool even before production APIs exist.

​
Document type was missing a key field

The Document type didn’t include room_id, which is required to associate documents with factory rooms. This gap would have surfaced as a bug when real API data came in. The mock layer caught it early.

​
Operational takeaways

  1. Mock data as QA: Building realistic mock documents forced every page in the navigation chain to actually render real content. Three bugs were found that wouldn’t have surfaced with placeholder data.
  2. Feature-flag migrations: The conditional-check pattern for auth made the Clerk purge a 30-minute task instead of a multi-day effort. Apply this pattern to any future provider swap (payments, analytics, etc.).
  3. Build gates hold: Both type-check and lint passed clean after all changes — zero warnings. The gate discipline continues to catch issues before they reach deployment.

​
Action items

  • Integrate BetterAuth properly (sign-in, sign-up, session management, API client tokens)
  • Promote feature/mock-documents branch through the full flow: PR to dev → release → staging → main
  • Replace mock document layer with real API calls once Golden Press service endpoints are available
  • Add E2E tests for the document navigation flow (floor plan → room → doc → edit)