PRODUCT-SPEC.md — AI Software Factory

Complete product specification. Detailed breakdowns live in docs/product/ (product-requirements, functional-requirements, ux-requirements, non-functional-requirements). This file is the authoritative summary that all task specs in docs/tasks/ must trace back to.

1. Product Vision

A modern, self-hostable, multi-tenant collaborative workspace platform inspired by the capabilities of Notion — a production-grade SaaS platform, not a prototype.

The platform combines:

• Document management · Block-based editor · Wiki · Knowledge base
• Databases · Project management · Task management · Kanban · Calendar · Timeline
• Dashboards · Forms · Comments · Collaboration · File management · Search
• Permissions · Automation · AI assistance · Templates · Integrations
• Public sharing · API access

Tenancy Model

Users
├── Workspaces
│   ├── Teams
│   ├── Members
│   ├── Pages
│   ├── Databases
│   ├── Files
│   ├── Comments
│   ├── Automations
│   └── Integrations
└── Personal Workspace (auto-created at registration)

A workspace is the top-level tenant. Every user automatically gets a personal workspace on registration.

2. Feature Scope

2.1 Core

Workspace management, user management, authentication, authorization, pages, nested pages, block editor (drag & drop, slash commands, right-click context menus, keyboard shortcuts), databases, database views, templates, file uploads, search, sharing, comments, version history.

2.2 Advanced

Real-time collaboration, mentions, notifications, relations, rollups, formulas, automations, database buttons, dashboards, forms, charts, AI, API, webhooks, import/export, public pages, audit logs.

2.3 Enterprise

SSO (SAML/OIDC), SCIM, RBAC, workspace policies, audit logs, data retention, encryption, organization management, usage limits, admin console.

3. The Page System

Pages are the fundamental content container. Every page supports:

Page
├── Icon
├── Cover
├── Title
├── Description
├── Properties
├── Blocks
├── Comments
├── Relations
├── Permissions
├── History
└── Child Pages

Pages can contain: text, headings, lists, images, videos, files, tables, databases, code, quotes, callouts, toggles, columns, synced blocks, links, bookmarks, embeds, forms, charts, child pages.

4. Block Architecture (Critical)

Do not implement the editor as one giant HTML document. Use a block tree.

interface Block {
  id: string;            // stable id, e.g. "blk_123"
  pageId: string;
  parentId?: string;
  type: BlockType;
  position: string;      // fractional ordering ("a0"), NEVER array indexes
  properties: JSON;
  content: JSON;
  createdAt: Date;
  updatedAt: Date;
}

Stable IDs + LexoRank/fractional position strategy. Example:

{
  "id": "blk_123",
  "type": "paragraph",
  "parentId": null,
  "position": "a0",
  "content": { "text": "Hello world" }
}

Block Types

Group	Types
Text	paragraph, heading_1, heading_2, heading_3, quote, callout
Lists	bulleted_list, numbered_list, todo, toggle
Media	image, video, audio, file, bookmark, embed
Code	code, equation
Layout	column, column_list, divider, spacer
Advanced	database, linked_database, table, chart, form, synced_block, child_page, child_database

5. Editor Requirements

Mouse: drag blocks, reorder, move into children, move between pages, resize columns and images, select / multi-select, context menu.

Keyboard: Enter, Shift+Enter, Backspace, Delete, Tab, Shift+Tab, arrows, Cmd/Ctrl+A, C, X, V, Z, Shift+Z (redo), K (command palette), B, I, U.

6. Slash Commands

Typing / opens a searchable command menu: /heading, /text, /todo, /bullet, /number, /toggle, /quote, /callout, /code, /image, /video, /file, /table, /database, /board, /calendar, /timeline, /chart, /form, /divider. /database dynamically creates a database block.

7. Context Menus

Block menu: Turn into · Duplicate · Copy · Copy link · Move to · Delete · — · Comment · Ask AI · — · Color · Background · — · Convert to (heading/quote/ callout/todo) · — · More.

Page menu: Open · Open in new tab · Duplicate · Rename · Move · Copy link · Favorite · Archive · Delete · Export · Share · Permissions.

8. Drag & Drop

Block dragging, nested dragging, cross-page dragging, database row dragging, sidebar page dragging, reordering, drop indicators, auto-scroll, multi-block dragging, drag between columns, drag files/images. Never store array indexes as permanent ordering — use fractional positions.

9. Database Engine

Databases contain records; each record is also a page (mirrors Notion).

Projects Database (rows: ID, Name, Status, Owner, Priority, Due Date, Tags, Budget)
        │
        └── each row opens a full Project Page (Properties + Block Content)

9.1 Property Types (22)

Title, Text, Rich Text, Number, Select, Multi Select, Status, Date, Date Range, Person, Email, Phone, URL, Checkbox, Files, Created Time, Created By, Last Edited Time, Last Edited By, Relation, Rollup, Formula, Button, Unique ID.

9.2 Views (9)

Table, List, Board, Gallery, Calendar, Timeline, Chart, Dashboard, Form. Each view keeps its own: filters, sort, group, visible properties, column width, card layout, color, density.

9.3 Filters

Nested boolean filters: AND / OR / NOT with grouping. Example: (Status = In Progress OR Status = Review) AND Owner = Current User.

9.4 Relations

One-to-one, one-to-many, many-to-many, bidirectional. Relations connect databases (Projects ↔ Tasks ↔ Employees ↔ Documents).

9.5 Rollups

COUNT, SUM, AVERAGE, MIN, MAX, PERCENT, UNIQUE. Example: Project rollups → Total Tasks = 4, Completed = 3, Completion = 75%.

9.6 Formula Engine

Safe parser/AST evaluator — never arbitrary JavaScript.

if(prop("Status") == "Done", 100, 0)

Functions: if, and, or, not, sum, average, min, max, dateAdd, dateBetween, now, concat, replace, contains, length.

9.7 Database Buttons

Actions: set property, create page, update page, archive page, duplicate page, send webhook, trigger automation.

10. Automation Engine

Trigger → Conditions → Actions   (executed via BullMQ + Redis workers)

• Triggers: record created/updated, property changed, page created, form submitted, schedule, webhook, manual button.
• Actions: update record, create page, send email, send webhook, create notification, assign user, change status, call integration, run AI action.

11. Forms

Form = questions (type, required, validation, mapped database property). Submission creates a database record. Use cases: customer feedback, bug report, employee request, contact form, project request.

12. Dashboards & Charts

Dashboards compose widgets: table, board, chart, number, calendar, timeline, text, linked database — resizable, draggable, configurable, filterable. Charts: bar, line, area, pie, donut, number. Config: x-axis, y-axis, group, filter, aggregation, color, legend.

13. Collaboration (Real-Time)

Browser → WebSocket → Realtime Server → {Presence, Cursors, Document updates, Comments}. Uses Yjs CRDT: multi-user editing, presence, cursor positions, avatars, conflict resolution, offline edits, reconnection, change sync.

14. Comments, Mentions, Notifications

• Comments attach to: page, block, text selection, database record. Create, reply, resolve, reopen, mention, react, delete, edit.
• Mentions: @user, @team, @page, @database with search popup.
• Notifications (in-app, email, webhook): mention, comment, assignment, page shared, task assigned, database change, automation, integration.

15. Search

Search everything: pages, blocks, databases, records, comments, files, users. Full-text + prefix + fuzzy, filters, recent searches, suggestions. Architecture: PostgreSQL → Search Indexer → OpenSearch. AI layer adds hybrid (keyword + semantic + metadata filters) RAG search.

16. File Management

S3-compatible object storage. Images, PDF, documents, videos, audio, archives, attachments. Pipeline: Upload → Virus scan → Metadata extraction → Thumbnail generation → Object storage → Database metadata.

17. Permissions (RBAC + Resource Permissions)

Roles: Owner, Admin, Member, Guest (workspace level) and resource-level levels: None, View, Comment, Edit, Full Access. Permissions apply at: organization, workspace, teamspace, page, database, database record, file. Every backend operation re-validates server-side.

18. Sharing & Public Pages

Scopes: private, workspace, team, specific users, public. Public URL: https://workspace.example.com/share/page-id. Options: allow comments, allow duplicate, allow search indexing, password, expiration.

19. Templates

Workspace templates, database templates, page templates, team templates. Example — Project Template: Overview, Goals, Requirements, Tasks, Timeline, Meeting Notes, Documents.

20. Import / Export

Import: Markdown, HTML, CSV, JSON, Notion export. Export: Markdown, HTML, PDF, CSV, JSON. Pipeline: Upload → Parser → Normalizer → Block conversion → Database conversion → Validation → Import.

21. AI Layer

AI Gateway with provider abstraction — OpenAI, Anthropic, Google, open-source models, custom OpenAI-compatible endpoints.

Capabilities: Ask AI, summarize, rewrite, improve writing, translate, extract data, generate page, generate database, generate formula, generate template, generate tasks, search workspace, answer questions.

Workspace AI search (RAG): Workspace → Content Chunker → Embedding Service → Vector Database → Hybrid Search (keyword + semantic + metadata) → LLM.

Page generation uses structured tool calls (never raw SQL): "Create a product launch plan" → Product Launch page with Objectives, Requirements, Timeline, Tasks Database, Risks, Team, Meeting Notes.

22. Public API & Webhooks

REST API v1: pages CRUD, databases (GET /databases/:id, POST /databases/:id/query, POST /databases/:id/records), search (POST /search), files (POST /files).

Webhook events: page.created|updated|deleted, database.created|updated, record.created|updated, comment.created, form.submitted, automation.executed. Flow: Event → Event Bus → Webhook Dispatcher → Retry Queue → External API.

23. Audit Logging

Events: user.login, page.created|updated|deleted|shared, permission.changed, database.created, record.created|updated, file.uploaded, automation.executed, api_key.created. Stored: actor, workspace, resource, action, timestamp, IP, user agent, metadata.

24. Security Requirements

Password hashing, JWT/session security, refresh token rotation, CSRF protection, rate limiting, input validation, SQL injection protection, XSS protection, content sanitization, file validation, malware scanning, permission checks, audit logging, API key hashing, secret encryption, secure cookies, CORS policy, security headers. Never trust frontend authorization.

25. Offline Mode

Editor → Local State → IndexedDB → Sync Engine → API/WebSocket. Offline page editing, offline block creation, offline database edits, reconnect, conflict resolution (CRDT), synchronization.

26. Performance Targets

Metric	Target
Initial page load	< 2 s
Editor interaction	< 50 ms
Local block movement	< 16 ms
Search response	< 500 ms
API p95	< 300 ms
Realtime update	< 200 ms

Large pages: virtualization, lazy loading, incremental rendering, pagination, caching, memoization. Databases: 100,000+ records without rendering all.

27. UI / UX

Layout: top bar + sidebar (Home, Inbox, Search, Favorites, Teamspaces, Private, Shared, Trash) + workspace content area. Responsive: desktop, tablet, mobile. Command palette (Cmd/Ctrl+K): create page, search, create database, open settings, switch workspace, invite user, toggle theme, export, import, ask AI. Theme: light / dark / system, design tokens, no hard-coded colors. Brand palette (recorded 2025, "colorful theme" request): the F1Soft fintech language from f1soft.com — vivid blue #2299dd (focus/ring + brand gradient), brand-blue #1976c2 primary (AA with white labels), crimson #a31e21 destructive, navy ink #0d1720 on a pale blue-white #f4f9fd canvas (light) and the deep-navy #0d1720/#14202b surface family with the bright blue primary (dark). All surfaces reference the oklch tokens in apps/web/src/app/globals.css; brand gradient/tints live in full-color --factory-brand-* tokens consumed via var() — components never hard-code colors. Accessibility: WCAG 2.2 AA — keyboard navigation, ARIA, screen readers, focus management, reduced motion, high contrast, accessible dialogs/menus, non-drag DnD alternatives.

28. MVP Boundary (First Production Milestone)

Authentication + Workspace + Pages + Block Editor + Drag/Drop + Slash Commands + Right-click menus + Database + Table View + Board View + Relations + Search + File Upload + Permissions + Comments.

Then: Calendar, Timeline, Gallery, Forms, Charts, Automation, Realtime, AI, API, Enterprise.