Design Doc: Docusaurus Merchant Help Center

Feature Name

Merchant Help Center — Static Documentation Site (Docusaurus)

Overview

Add a standalone Docusaurus site (apps/docs) to the FlowPOS monorepo that serves as the merchant-facing help center. It hosts how-to guides, FAQs, video embeds, and release notes for FlowPOS retail and restaurant merchants. The site is deployed to GCP (Cloud Storage + CDN or Cloud Run) via the existing GitHub Actions CI/CD pipeline.

Project Context

• Project: FlowPOS
• Monorepo: pnpm workspaces (apps/docs as the new app)
• Deployment: GCP (Cloud Storage static export or Cloud Run Docker container)
• CI/CD: GitHub Actions (mirrors the pattern of apps/landing-page)
• i18n: English (en) as primary, Spanish (es) as secondary — using Docusaurus i18n plugin
• Secrets: Doppler (same pattern as other apps)

Scope

What this spec must cover

1. New app scaffold — apps/docs added to the pnpm workspace with Docusaurus 3.x.
2. i18n configuration — es as default locale, en as alternate; translation files live in apps/docs/i18n/.
3. Content structure — top-level doc categories mirroring FlowPOS product areas:
   • Primeros Pasos (Getting Started)
   • Ventas y Caja (Sales & POS)
   • Inventario (Inventory)
   • Clientes y CRM
   • Reportes y Metabase
   • Facturación Electrónica (FEL)
   • Configuración (Settings)
4. Search — Docusaurus built-in Lunr search (offline, no Algolia dependency at launch).
5. Chatwoot widget slot — a placeholder/config for embedding the Chatwoot live-chat widget via @chatwoot/docusaurus-plugin (implemented in the Chatwoot spec).
6. Deployment pipeline — a new GitHub Actions workflow (deploy-docs.yml) that:
   • Builds the static site (pnpm --filter docs build)
   • Uploads to GCP Cloud Storage bucket or deploys to Cloud Run
   • Runs on push to main (production) and develop (staging)
7. Versioning — no versioned docs at launch; single current version only.
8. MDX support — enabled so React components (e.g., video embeds, callout boxes) can be used inside .mdx files.

Out of scope

• Backend API changes
• Database changes
• Authentication / gated content (docs are public)
• Algolia search (future milestone)
• Automatic content sync from the backend

Key Technical Decisions

Decision	Choice	Reason
Framework	Docusaurus 3.x	React-native, i18n, MDX, active OSS
Package manager	pnpm (workspace)	Consistent with monorepo
Build output	Static export	Cheapest GCP hosting, CDN-friendly
Locale default	es	Primary merchant market is Guatemala
Styling	Docusaurus default theme + Tailwind (optional)	Keep low-friction

Speckit Command

Primary:

/speckit.specify Add a new `apps/docs` Docusaurus 3 site to the FlowPOS pnpm monorepo as the merchant-facing help center, with English-first, Spanish i18n, MDX support, a Chatwoot widget slot, and a GCP deployment GitHub Actions workflow mirroring the landing-page deploy pattern.

Alternative:

/speckit.specify Scaffold `apps/docs` as a Docusaurus 3 static site in the pnpm workspace covering FlowPOS merchant documentation (Getting Started, Sales, Inventory, FEL, Reports), configured for es/en i18n, built-in Lunr search, MDX, a `@chatwoot/docusaurus-plugin` slot, and deployed to GCP Cloud Storage via GitHub Actions on pushes to `develop` (staging) and `main` (production).

Why the primary is best: The primary is concise and scope-bounded. It names the new app path, the framework version, the monorepo integration point, the two non-negotiable runtime features (i18n + Chatwoot slot), and the deployment requirement — all without prescribing implementation details that Speckit should decide. The alternative is useful if Speckit needs more content-level context.