AI-Powered-Documentation-Workspace

0 · Executive summary

This product is an AI-powered professional documentation workspace. Its purpose is to help users create, organize, improve, rewrite, summarize, publish, and maintain professional documentation with the help of ChatGPT / AI — a modern AI-first documentation platform with productivity quality on par with the best in the category, built as an original high-end product (no Notion branding, logo, exact UI, proprietary design, colors, or copyrighted elements). Users create workspaces, organize pages and subpages with unlimited nesting, edit with a block-based editor (28 block types), build flexible databases with table / board / list / gallery / calendar views, use a library of professional templates, run AI text transforms on selection, query a RAG knowledge base scoped to their workspace, search globally with Cmd/Ctrl + K, share pages privately or via tokenized public link, and audit every important action. The product is desktop-optimized and mobile-responsive from v1 on a clean Laravel core with a thin Livewire UI. Filament powers admin only.

0.5 · Design principles & professional posture

Twelve principles, ordered. Each is a tie-breaker for design disagreements: when two implementation choices would both satisfy the spec, the higher-numbered principle wins. New contributors should read these once and refer back when a design call feels ambiguous.

1. Documentation is the product. Every UX decision is evaluated by whether it makes a documentation-author faster, calmer, and more confident. Editor speed beats feature count. Latency budgets in §15 are non-negotiable.

2. AI is a peer, not a side feature. Every text surface, every block, every cell, every comment participates in the AI + RAG loop. There is no "AI tab" — the AI lives inline, contextually, with citations.

3. Preview before apply. AI never writes user content without an explicit human confirmation. This is non-negotiable across web, mobile-web, and the future native client. Auto-apply is a security and trust regression.

4. Workspace-scoped everything. RAG never crosses workspace boundaries. Search never crosses workspace boundaries. Templates marked global are read-only and curated by admins. Cross-workspace leakage is a SEV-1 incident.

5. Mobile-web before native. The mobile-web experience must be fluent before a SwiftUI app ships. No feature is "desktop-only" without an explicit mobile_omitted note in the Registry row and a one-line justification.

6. Lazy load by default. The page tree, the editor block list, the database row set, and the search result list all paginate. Loading a workspace must not load a workspace. Cursor pagination on every hot list.

7. Original product, original UI. No Notion branding, logo, exact UI, design tokens, icon set, or proprietary patterns. Inspiration is fine; pixel imitation is forbidden. The CI lint ui-originality-check keeps a regex denylist of visual tells (specific class names, exact hex colors, exact iconography).

8. One brain, two surfaces. The Laravel API is the single backend; the web client and the future SwiftUI client are both consumers. Domain logic never lives in either client. The parity test asserts this.

9. Event-based history wins over snapshots. Page versions are diffs, not full payloads. Restore is a deterministic replay. Storage cost is bounded by edit count, not page size.

10. Sanitization at the edge. All user-provided HTML, Markdown, and AI output passes through SanitizerService before persistence. There are no "trusted blocks" — even server-generated content is sanitized on write.

11. Idempotent jobs. Every queued operation (RAG reindex, export, file commit, AI transform persistence) is keyed by a content hash and is safe to retry. Failed jobs auto-retry with capped exponential backoff; the cap is documented in §15.

12. Audit everything mutable. Every state change writes one row to activity_logs. The audit log is append-only, includes actor + IP + user-agent, and ships with the export bundle. No silent state changes.

1 · Product vision

A documentation operating system powered by AI, not a simple editor. The seven canonical verbs are first-class capabilities, each backed by concrete services in this pack:

Every document, page, block, database row, file, comment, version, AI transformation, share link and permission is modeled cleanly and scalably. The architecture supports:

• single-user → small team → large team scaling without rewrite,

• desktop web, tablet, mobile web, and a future SwiftUI client,

• workspace-scoped AI with RAG that cites internal pages,

• a templating system covering SOPs, product specs, API docs, wikis, roadmaps, meeting notes, knowledge bases.

2 · Architecture overview

flowchart LR
	Web(["Web client<br>Livewire 3 + Alpine + Tailwind"]) -->|HTTPS + Reverb WS| API["Laravel API + Web"]
	Mob(["Mobile web / future SwiftUI"]) -->|HTTPS + SSE| API
	Adm(["Admin operator<br>Filament panel"]) -->|HTTPS| API
	API --> Pages["PageService"]
	API --> Blocks["BlockService"]
	API --> DBs["DatabaseService"]
	API --> Search["SearchService"]
	API --> AI["AiTransformService"]
	API --> RAG["RagService"]
	API --> Share["ShareService"]
	API --> Files["FileService"]
	API --> Activity["ActivityLogService"]
	AI --> Providers{"Provider"}
	Providers -->|OpenAI| OAI["OpenAI"]
	Providers -->|Claude| CLA["Anthropic"]
	RAG --> Index["RagIndexer<br>(queued)"]
	Index --> Store[("rag_chunks<br>(MySQL JSON / pgvector opt-in)")]
	Files --> S3[("S3-compatible storage")]
	API --> Cache[("Redis<br>cache / locks / queues / Horizon / Reverb")]
	API --> DB[("MySQL / MariaDB")]

3 · Tech stack (locked)

4 · The 24 modules (canonical catalogue)

5 · Database plan (23 tables, schema overview)

Every table: PK id (bigint unsigned), created_at / updated_at, soft-delete where relevant, FK with restrictOnDelete or cascadeOnDelete as noted. JSON columns are validated by service-layer schema. Hot-path indexes are listed inline.

6 · API surface (REST + Sanctum)

All responses paginated (?per_page capped at 100). Cursor pagination on hot lists. Every endpoint goes through a Policy; never trust the client.

7 · Implementation phases (P0 → P6)

Policy: each phase ships its own migrations, services, Livewire components, Filament resources (if applicable), tests, and docs/ updates. No phase merges without green CI + a CHANGELOG_AI.md entry.

8 · Test plan

9 · Docs plan

13 mandatory docs/*.md files + 6 .cursor/rules/*.mdc. Each doc carries a SoT spec header (mirrored from its Notion page).

Cursor rules: .cursor/rules/project-overview.mdc, database.mdc, editor.mdc, security.mdc, rag.mdc, mobile.mdc.

10 · §SoT · STV sub-registry (mirrored into parent master §SoT.5)

This is the STV sub-registry of the parent project. The rows below are the canonical list for the STV product line and are pointed to from the parent master §SoT.5 (single source of truth: this section). Conflict ladder within STV: SPEC-STV-HUB > Architecture-tier (-01, -02) > Specification-tier (-03 … -11, -13) > Reference-tier (-12). Cross-product-line conflicts: parent SPEC-HUB v1.4.0+ wins (it defined the §SoT system).

11 · Acceptance criteria (project is shippable when)

1. User can sign up, create a workspace, invite a member with a role.

2. User can create pages and subpages with unlimited nesting.

3. Block editor supports all 28 types; slash menu, drag handle, floating toolbar work on desktop and mobile.

4. Autosave is visible and reliable; no edit is lost on tab close.

5. Version history records every meaningful edit and supports restore.

6. User can create a database, define properties, add rows, switch between table / board / list / gallery / calendar views, filter and sort server-side.

7. Templates: instantiate from library; save page as template; preview before instantiate.

8. AI selection editor: select text → ask → preview → replace / insert below / copy / discard. Never auto-applies. Rate-limited.

9. RAG: workspace-scoped index runs in queue; AI Q&A cites internal pages; ON/OFF per workspace.

10. Global search via Cmd/Ctrl + K: pages, blocks, files, comments, databases, templates.

11. Sharing: private / workspace / per-user / tokenized public link. View, comment, edit modes. Public pages rate-limited.

12. Comments + mentions + activity feed work; admin sees full audit log.

13. Mobile web is fluent: editor, search, share, AI, RAG all usable on phone.

14. All 13 docs/*.md mirror their Notion specs and pass claude-rules-lint + spec-registry-lint.

15. Pest test suite green; API contract test green; policy tests green.

16. No secret value reachable through any response, doc, or RAG chunk.

17. UI is clean, modern, fast, and original (no Notion branding or copyrighted assets).

12 · Open questions (carry into next refactor pass)

1. Self-host vs SaaS pricing model — affects storage limits + plans table shape (not in v1 schema).

2. Realtime cursors (Yjs / Tiptap collab) — defer until P3 post-launch.

3. pgvector opt-in or stay JSON-only for v1? Default: JSON; opt-in flag in rag_settings.

4. Meilisearch managed (cloud) vs self-host — both supported by Scout.

5. Block-level encryption for sensitive workspaces — gated to enterprise tier.

6. Native iPhone (SwiftUI) cut-in — only after mobile-web parity is signed off.

7. AI provider default — OpenAI gpt-4.1 vs Claude 3.7-sonnet; per-workspace setting.

8. Public share password protection + expiration — design ready, ship in P5.

13 · Sub-pages (live, nested under this hub)

The 13 STV sub-specs are now physically nested under this hub so the tree reads master hub → STV-HUB → STV-XX cleanly. The canonical list is:

• SPEC-STV-00 · Product Overview & Goals — 🎯SPEC-STV-00-Product-Overview

• SPEC-STV-01 · Architecture & Modules — 🏗️SPEC-STV-01-Architecture

• SPEC-STV-03 · API Endpoints Reference — 🔌SPEC-STV-03-API-Endpoints

• SPEC-STV-04 · Editor System & 28 Block Types — ✏️SPEC-STV-04-Editor-System

• SPEC-STV-05 · Databases / Tables System — 📊SPEC-STV-05-Databases

• SPEC-STV-06 · Template System — 📐SPEC-STV-06-Template-System

• SPEC-STV-07 · RAG Knowledge Base — 🧠SPEC-STV-07-RAG-System

• SPEC-STV-08 · AI Writing Assistant — ✨SPEC-STV-08-AI-Assistant

• SPEC-STV-09 · Search — 🔍SPEC-STV-09-Search

• SPEC-STV-10 · Mobile & Desktop UX — 📱SPEC-STV-10-Mobile-UX

• SPEC-STV-11 · Sharing, Permissions, Security, Scalability, Admin — 🛡️SPEC-STV-11-Sharing-Security

• SPEC-STV-12 · Comments, Activity, Import/Export, Testing, Docs, CHANGELOG — 📚SPEC-STV-12-Comments-Activity

• SPEC-STV-13 · Mobile Gestures & Text Selection Editor — 👆SPEC-STV-13-Mobile-Gestures

14 · Cross-cutting non-functional requirements

The 24 modules of §4 each pass through these gates. Treat them as horizontal contracts: any module that fails one of these is not shippable, regardless of which phase landed it. A regression on any §14 gate opens a Hardening (P11) or Performance (P12) ticket in the same edit pass.

§14.1 · Accessibility (WCAG 2.2 AA target)

• Keyboard parity for every editor interaction (slash menu, drag handle, floating toolbar, version restore, slash actions, public reader navigation).

• Focus rings on every interactive element; prefers-reduced-motion respected on every animation.

• Color contrast ≥ 4.5:1 for body, ≥ 3:1 for large text; tested in light + dark themes.

• Screen-reader names for icons (aria-label or visually-hidden text); no icon-only buttons without labels.

• Skip-to-content links on every page; sensible heading order (no skipped levels) inside the editor.

§14.2 · Internationalization

• All UI strings flow through __() (Laravel) or the JS equivalent; no hard-coded English in views or components.

• Date and number formatting via Intl APIs and Laravel formatLocalized(); never toLocaleString() without an explicit locale.

• RTL layout supported in the editor and the public reader (mirrored toolbars, mirrored drag handles, mirrored block menus, mirrored slash menu anchor).

• Content language is per-page (used by AI prompts and search analyzers); UI language is per-user (used by the chrome).

§14.3 · Observability

• Every queued job emits a start and end log line with workspace_id, actor_id, entity_type, entity_id, duration_ms.

• Every AI call records provider, model, tokens_in, tokens_out, cost_usd in ai_text_transformations.

• Failed jobs panel in Filament admin; Sentry breadcrumbs scoped to workspace_id (never user PII).

• Slow-query log on MySQL / MariaDB ≥ 200 ms; weekly review by Backend architect.

• A workspace-scoped /admin/observability dashboard (Filament) surfaces queue depth, search latency, AI cost, RAG freshness.

§14.4 · Privacy & data handling

• PII columns explicitly listed in docs/SECURITY.md; the export pipeline scrubs PII for public exports.

• RAG ingestion excludes any block whose ancestry contains a private:true marker; verified by an indexer test.

• Audit log retention: 365 days default, configurable per workspace.

• A user-initiated workspace deletion runs a queued, fully-audited purge job; tombstones land in activity_logs with a purge action.

• All exports of personal content require a fresh password challenge; tokens minted for export are single-use and expire in 15 minutes.

15 · Performance budgets & SLOs

These are aspirational v1 budgets; tightening is a SPEC-STV-HUB minor bump. Failing any budget for two consecutive weeks opens a Hardening or Performance ticket against the offending module.

16 · STV-side glossary