q-blog/docs/Q-Blog_1.0.0_ROADMAP_conceptual.md

**TL;DR:** Below is a higher-level, technical “how we’ll do it” roadmap for Phases 0–10. It explains approaches, contracts, guardrails, and sequencing—no filenames or concrete code yet.

---

# Q-Blog → 1.0.0: Technical Roadmap (Conceptual “How”)

## Phase 0 — Orientation & Quality Bar

**How:**

- Define protected user journeys and SLIs/SLOs (e.g., time-to-interactive, save success rate, keyboard reachability).
- Adopt a single “definition of done” template (accessibility, tests, docs, telemetry hook, error state).
- Establish a lightweight decision record format (context → options → decision → impact) for any cross-cutting choice.

---

## Phase 1 — Project Docs & Working Agreements

**How:**

- Author concise, source-of-truth docs: a high-level architecture map (UI/state/data flows), a testing strategy pyramid, an accessibility standard, and contribution rules.
- Record initial decisions (editor stack, state mgmt, theming, data shape conventions).
- Add a changelog discipline (human-readable entries grouped by “Added/Changed/Fixed/Removed/Docs/Tests”).
- Define semantic labels for issues/PRs (type, area, effort) to enable predictable triage.

---

## Phase 2 — Test Harness & Linting Baseline

**How:**

- Testing layers:

  - **Unit & component:** Vitest + JSDOM + React Testing Library; global test setup for matchers/mocks.
  - **Integration/smoke (later):** small number of Playwright/Happy-path flows (create/edit/publish).

- Coverage:

  - Enforce thresholds at the package level; exclude generated/fixture code; surface a coverage report artifact.

- Linting/formatting:

  - ESLint (flat config) with TypeScript, React, and **jsx-a11y**; Prettier for formatting; consistent import ordering.

- Fast feedback:

  - Watch mode locally; pre-push hooks run **lint + typecheck + tests (changed files)**.

- CI scaffolding (conceptual):

  - Separate jobs for install/cache, lint/typecheck, unit/component tests, and (later) e2e smoke; cache node modules; artifact uploads for coverage.

---

## Phase 3 — Correctness Sweep

**How:**

- Dependency hygiene:

  - Align UI toolkit imports to current major; remove legacy namespaces; verify peer-dep ranges; lock versions for determinism.

- Type safety:

  - Replace broad `any`/suppressed regions with minimal interfaces and discriminated unions where helpful.
  - Introduce a “strict mode budget”: upgrades gated by keeping type errors at zero.

- State/data flows:

  - Standardize async lifecycles (`idle/loading/success/error`) and empty states; unify error objects (message + code + recoverability).

- Image/media safety:

  - Enforce text alternatives policy; handle failed loads with fallbacks; guard upload constraints (size/type).

- Cross-browser sanity:

  - Run a small matrix (Chromium/WebKit/Firefox) in CI for a smoke render test.

---

## Phase 4 — Accessibility Baseline

**How:**

- Semantics & landmarks:

  - Use structural regions (header/nav/main/footer) and a skip-to-content anchor; ensure a single H1 per view.

- Keyboard & focus:

  - Trap focus in modals/popovers, restore focus on close, visible outlines; consistent Tab/Shift+Tab order; Esc closes transient UI.

- Names/roles/states:

  - Deterministic accessible names for controls; toggles use `pressed` state; forms have programmatic labels and error/help text wiring.

- Live updates & motion:

  - Polite live region for async progress; respect `prefers-reduced-motion`; avoid seizure risk (no flashing).

- Testing:

  - Automated axe checks in component tests for critical views; a short manual keyboard checklist per protected journey.

---

## Phase 5 — UX & IA Touch-up

**How:**

- Navigation model:

  - Clarify primary vs. secondary navigation; ensure routes map cleanly to the data model (current blog scope).

- Consistency system:

  - Define tokens for spacing/typography/contrast; standardize button/empty/error patterns; unify iconography.

- Editor ergonomics:

  - Deterministic toolbar enable/disable; clear state for draft vs. published; undo/redo affordances; autosave with visible status.

- Content lifecycle:

  - Uniform toasts/banners for success/failure; retry affordances on transient failures; protective confirms on destructive actions.

---

## Phase 6 — Data Model Extension: Multiple Blogs per Name

**How:**

- Domain relationships:

  - **Name** (account) 1..N **Blog**; **Post** 1..1 **Blog**; keep **Post → Blog** immutable after creation (prevents cross-blog drift).

- Identifiers & URLs:

  - Introduce stable blog handles (human-friendly, unique per name) that compose into routes; add collision policy and normalization rules.

- State management:

  - Represent “current blog” as first-class app state; selector scoping so lists/metrics derive from the active blog.

- Migrations:

  - Backfill: create a default blog per name and attach historical posts; record migration version on the data root to allow repeatable ops.

- UX:

  - Blog switcher in global nav; “create blog” guided flow with handle validation and preview; clearly scoped creation forms.

- Indexing & constraints (backend/API expectations):

  - Unique composite index (name, blog handle); foreign key from posts to blog id; server rejects cross-blog updates.

---

## Phase 7 — Permissions Model: Shared Blogs

**How:**

- Role model (lean start):

  - **Owner** (full control), **Editor** (edit any post, manage drafts), **Author** (create/edit own posts), **Viewer** (public, implicit).

- Invitations:

  - Tokenized invite flow with expiration; acceptance binds a name to a role on a blog; owner can revoke.

- Enforcement:

  - All write endpoints check role → operation matrix; UI gates controls (disable/hide) but never trusts the client.

- Attribution & activity:

  - Store author id and updated-by on posts; optional lightweight activity log for edits/publishes; surface attribution in UI.

- Conflicts:

  - Last-writer-wins with ETag/if-match semantics or revision numbers; reject stale writes; small conflict UI with diff view (stretch goal).

---

## Phase 8 — Performance & Resilience

**How:**

- Rendering:

  - Keep lists virtualized; hydrate only what’s visible; memoize high-churn components; defer non-critical work with idle callbacks.

- Network:

  - Structured fetch layer with timeouts, abort support, and retry/backoff on idempotent GETs; idempotency keys on create/update to prevent dupes.

- Perceived speed:

  - Optimistic UI where safe (e.g., draft saves); skeletons/spinners with progress semantics; prefetch likely next views.

- Failure handling:

  - Standard error surface (banner/toast + inline details); retry path; offline detection with queued drafts.

- Metrics:

  - Track Web Vitals and action latencies; set budgets (e.g., LCP, INP) and regressions fail CI perf checks (can be a nightly).

---

## Phase 9 — Internationalization & Theming Consistency

**How:**

- Strings:

  - Centralize UI strings under a namespace scheme; ensure interpolation is safe; default English bundle with stubs for others.

- Formatting:

  - Use Intl APIs for dates/numbers/plurals; avoid manual formatting; prepare RTL-safe layouts (logical properties).

- Themes:

  - Single source for color/spacing/typography tokens; verify contrast programmatically; support `prefers-color-scheme`.

---

## Phase 10 — Observability, Security & Release Readiness

**How:**

- Observability:

  - Error boundaries with user-friendly fallback views; structured client logs (level, code, context) routed to a collector; anonymized action breadcrumbs for repro.

- Security posture:

  - Input validation at boundaries; sanitize rich text; content-security-policy hardening; permission checks at every write; least-privilege tokens.

- Migrations & backups:

  - Versioned migrations with idempotent steps; pre-prod dry run; exportable backup of critical entities; rollback procedure.

- Release discipline:

  - SemVer tags; changelog; migration notes; upgrade guide; “go/no-go” checklist (tests green, a11y checks pass, metrics within budget).

---

## Cross-cutting Technical Principles

- **Contracts first:** Define data and role contracts before wiring UI; document them in the repo and tests.
- **Small vertical slices:** Ship changes end-to-end (schema → API → state → UI → tests) in thin increments.
- **One source of truth:** Centralize constants (roles, statuses, limits) and import them everywhere.
- **Guardrails by default:** Lint/type/test/a11y checks run locally and in CI; merges require green gates.
- **Telemetry with restraint:** Collect only what’s necessary for quality; feature-flag any new collection.

---

## Assumptions & Risks

- We control both client and API contracts (or can negotiate them).
- Current data fits a clean migration to per-name default blogs without manual reconciliation.
- Editor content can be sanitized without breaking required formatting.
- Minimal E2E is enough for confidence; we can expand later if flakiness appears.