Flow Docs

2026-04-20 — Docs Audit + Landing Rebrand

4 min read

2026-04-20 — Docs Audit + Landing Rebrand

Due interventi paralleli sul doc site: rebrand visivo della homepage

  • creazione di una Brand Book completa, e audit sistematico dei contenuti stantii lasciati dietro dalla migrazione Supabase-only del 2026-03-29.

Branch

edit/web-brand-parity-docs in flow_docs/, off main.

Landing + Brand Book

Sostituito il template di default di Docusaurus con una landing Flow-brand completa:

  • Hero ink con glow corallo/violet radiale, badge brand, shimmer gradient sul wordmark, CTA primario (Entra nei docs) + secondario (Brand Book).
  • BrandMark SVG inline che usa il bezier locked (M 60 340 C 310 10, 700 590, 940 230), stesso disegno del lockup web marketing.
  • Griglia 6 sezioni con card tinted (coral/violet/ink/emerald/ amber/blue) che puntano alle sei aree principali dei docs.
  • RepoStrip ink con i tre repo del progetto (flow-platform, flow-mobile, flow-docs).
  • CSS module con token locali per non dipendere da Infima; shimmer animation rispetta prefers-reduced-motion.

Nuova pagina /docs/project/brand-book: un manifesto che vive la filosofia che descrive. Ink cover con shimmer, Brand Mark con anatomia annotata, palette swatches, gradient signature animato, lockup grid (horizontal + stacked × light + dark), scala tipografica renderizzata a dimensione reale, DO/DON’T voice cards, tabella superfici canoniche. Stili co-locati in brand-book.module.css.

Navbar espansa con link diretti a Architettura e Brand Book; footer con una colonna Documentazione (Getting Started + Architettura + Brand Book + API Reference) oltre alla colonna Repos esistente. Copyright passato da “Flow Team” a “Flow · Vivi il momento.” per allineamento con la tagline web.

Audit — contenuti stantii rimossi o etichettati

L’audit ha identificato due categorie di contenuto fuori tempo:

(A) Rewrite completo — documenti “hero” del doc site

Documenti che i nuovi contributor leggono per primi:

  • docs/intro.md → stack label corretta (era “Node.js microservices”), aggiunta admonition sulla migrazione Supabase-only.
  • docs/getting-started/overview.md → diagramma ASCII microservizi rimpiazzato con diagramma Supabase-only, repo table aggiornata, aggiunta sezione “Prossimi passi” con link guidati.
  • docs/architecture/overview.md → rewrite completo dall’inglese microservizi all’italiano Supabase-only. Tech stack table, lista Edge Functions, sezione “Cosa NON c’è” per documentare le scelte anti-pattern.
  • docs/backend/database-schema.md → header rimpiazzato (era “hybrid dual-database”), admonition storica su Mongo/Redis legacy.
  • docs/backend/api-reference.md → da stub “Coming soon” a reference completa (PostgREST + Edge Functions + Realtime con esempi di codice).

(B) Banner pre-migrazione — documenti legacy conservati

Documenti lunghi (500+ righe) scritti per l’architettura microservizi e ancora utili come storia. Aggiunta :::warning::: admonition in cima a ciascuno, senza toccare il contenuto:

  • docs/development/guide.md (477 righe)
  • docs/deployment/guide.md — banner + setup attuale in 4 righe
  • docs/architecture/technical-architecture.md (1048 righe)
  • docs/architecture/improvements.md (76 righe)
  • docs/architecture/architecture-issues.md (561 righe)

(C) Categoria Issues riformulata

La directory /docs/issues/ contiene 12 proposte infrastrutturali (Event Bus, Redis Streams, CDC Mongo→Postgres, gateway caching, ecc.) tutte scritte per i microservizi. La label del category sidebar è passata da “⚠️ Issues & Improvements” a “⚠️ Issues (archivio pre-migrazione)” e è stata aggiunta una generated-index page con la descrizione del contesto storico.

Build Docusaurus segnalava 7 broken links e 5 broken anchors:

  • docs/project/overview.md → 4 link a file UPPERCASE inesistenti (TECHNICAL_ARCHITECTURE.md, API_DOCUMENTATION.md, ecc.) rimpiazzati con path reali.
  • docs/architecture/architecture-issues.md → ../ROADMAP.md → path reale ../project/roadmap.
  • docs/development/guide.md → DEPLOYMENT_GUIDE.md fix.
  • docs/project/changelog/2026-04-10-web-brand-parity.md → due path roadmap corretti (extra ../).
  • docs/roadmap/specs/2026-04-08-web-brand-parity-design.md → link filesystem esterni al docs tree convertiti in code span.
  • docs/legacy/Flow_Complete_Project_Documentation.md → 5 anchor link a sezioni mai scritte convertite in placeholder text.

(E) Cleanup infrastrutturale

  • Rimosso src/components/HomepageFeatures/ (non più usato dopo il rebrand della landing).
  • docusaurus.config.ts: migrato onBrokenMarkdownLinks dentro markdown.hooks.onBrokenMarkdownLinks per pre-posizionarsi alla v4.

Verifica

Build finale: 0 broken links, 0 broken anchors, 0 warning di deprecazione config.

✔ Server: Compiled successfully in 6.53s
✔ Client: Compiled successfully in 9.36s
✓ Generated static files in "build".

Non fatto (flaggato per sessioni separate)

  • Rewrite completo di docs/development/guide.md e docs/deployment/guide.md in versione Supabase-only (banner intermedio aggiunto come mitigazione immediata).
  • Pipeline error-logging del web admin portal verso Supabase (task spawn-ata).
  • Plan upgrade Flutter/CMake/Firebase C++ SDK per flow_mobile (task spawn-ata).

Commit list

a4d9a76 feat(landing): redesign Docusaurus home with branded hero + section grid
b743bac docs(intro): correct stale stack label, note Supabase-only migration
9636e47 fix(intro): correct migration spec link path (specs/ not plans/)
049e7ab docs(brand): add Brand Book page with living design system
56609e8 chore(docs): remove unused HomepageFeatures template component
d974630 docs(architecture): rewrite overview to reflect Supabase-only reality
1eac0f3 docs(getting-started): replace stale microservices diagram with Supabase flow
c216261 docs(backend): align DB schema header + API reference with Supabase-only
c1890ff docs: add pre-migration warnings to development + deployment guides
9d5a6ef fix(landing): point primary CTA to /docs/ root
1b42634 fix(docs): resolve broken internal links flagged by Docusaurus build
09f03a1 fix(docs): remove dead TOC links in legacy project documentation
bb17214 chore(config): migrate onBrokenMarkdownLinks into markdown.hooks for v4
199f9ca docs(issues): reframe Issues section as pre-migration archive
1a6c801 docs(architecture): add pre-migration warnings to legacy architecture docs
bed3adc feat(docs): expand navbar + footer with direct links to key pages

Graph View