Silos/README.md

# Silos

A collaborative workspace platform — your knowledge, your team, one place.

## Tech Stack

- **Frontend:** React + TypeScript + Tailwind CSS
- **Backend:** FastAPI + SQLAlchemy
- **Database:** PostgreSQL (users, auth) + MongoDB (whiteboards, sketches)

## Quick Start

### 1. Start databases

```bash
docker compose up -d
```

### 2. Backend

```bash
cd backend
copy .env.example .env
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

### 3. Frontend

```bash
cd frontend
npm install
npm run dev
```

- Landing page: [http://localhost:5173](http://localhost:5173)
- Login page: [http://localhost:5173/login](http://localhost:5173/login)
- API docs: [http://localhost:8000/docs](http://localhost:8000/docs)

## Project Structure

```
Silos/
├── frontend/     # React + Tailwind
├── backend/      # FastAPI
└── docker-compose.yml
```

## Feature Progress

### Phase-wise Confluence-inspired platform roadmap

The platform is being delivered in focused phases so each collaboration and
content-management capability is usable before the next layer is added.

#### Phase 1 — Page hierarchy and lifecycle foundation (complete)

- Added `parent_page_id` to document creation, updates, responses, and frontend
  document records.
- Added parent validation so a page cannot parent itself, attach to an
  inaccessible page, or attach directly to a space as a page parent.
- Added child-page creation from the current page.
- Added hierarchical sidebar navigation with expand/collapse behavior.
- Added a three-dot page actions menu with child-page creation, duplication,
  archive, permanent delete, and close actions.
- Archived pages are excluded from normal dashboard and space navigation.
- Existing space membership, sharing, and explicit Edit → Update → Publish
  behavior remain intact.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`

#### Phase 2 — Templates and page creation flows (complete)

- Added reusable Silo page templates for blank pages, meeting notes, project
  plans, and how-to guides.
- Added page-template creation to the global Create menu.
- Updated the Templates flyout to use the same shared page-template definitions.
- New pages created inside a space preserve the space relationship.
- New pages created from a page context preserve the parent-child relationship.
- Added a Confluence-inspired inline `+` action beside each Silo page in the
  sidebar. It creates a child page under that page and opens it immediately.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`

#### Phase 3 — Sidebar page management and richer creation flows (complete)

- Replicated the Confluence-inspired sidebar hierarchy treatment with
  disclosure arrows for parent pages and bullet markers for leaf/child pages.
- Added inline child-page `+` controls beside page names.
- Added per-page three-dot menus with Edit, Rename, Star, Copy link, Make a
  copy, Move, Archive, and Delete actions.
- Added inline page renaming with Enter/save behavior.
- Added a Move page dialog with top-level placement and parent-page selection.
- Prevented moving a page below itself or one of its descendants.
- Added shared styling for the sidebar page-action menu.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`

#### Phase 4 — Collaboration foundation (complete)

- Added persisted comments for accessible documents.
- Added threaded-comment parent validation at the API boundary.
- Added author-only comment deletion.
- Added a page-level Comments panel with loading, empty, error, create, and
  delete states.
- Reused existing document sharing and editor/viewer permissions for comment
  access.
- Added a comments entry point beside the page Edit/Update/Publish controls.
- Added MongoDB indexes for document comment retrieval.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`

#### Phase 5 — User-authored templates and categories (complete)

- Added owner-scoped persisted templates in MongoDB.
- Added template categories, descriptions, emoji labels, and starter content.
- Added template CRUD endpoints under `/api/v1/templates`.
- Added template indexes and authenticated ownership checks.
- Added a Templates flyout flow for creating, filtering, using, and deleting
  user templates.
- Custom templates create new Silo pages while preserving their starter
  content and draft state.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`

#### Phase 6 — Template sharing and placement selection (complete)

- Added owner-controlled template sharing by email or username.
- Shared templates are included in the authenticated template library.
- Added a template sharing dialog with explicit dismissal.
- Added placement selection for pages created from custom templates:
  top-level, selected space, or selected parent page.
- Preserved the existing hierarchy and document-access validation path for
  placement targets.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`

#### Phase 7 — Collaboration expansion (complete)

- Added `@username` mention parsing against registered users.
- Added persisted mention notifications with unread/read state.
- Added a workspace notification bell and notification dropdown.
- Added persisted page activity entries for comment creation and
  comment resolution/reopening.
- Added an Activity view alongside the Comments panel.
- Added nested threaded replies using the existing `parent_id` model.
- Added resolve/reopen controls with access-checked API mutations.
- Preserved the existing WebSocket collaboration presence and live content
  channel, including peer updates when users join or leave.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`
- FastAPI application import and route registration

#### Phase 8 — History, publishing, and operational polish (complete)

- Added persisted document version snapshots before content/title updates.
- Added version history listing and access-controlled restore.
- Added HTML and plain-text page export endpoints and page controls.
- Added keyboard save (`Ctrl/Cmd+S`) and Escape dismissal for history.
- Added accessible names, live editor status, history labels, and notification
  controls.
- Preserved the existing MongoDB text index and access-aware search behavior.
- Added three Playwright browser regression specs covering history, export, and
  keyboard/accessibility journeys.
- Added `npm run test:e2e` and `runtime-validation-report.md`.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`
- FastAPI application import and route registration
- `cd frontend && npm run test:e2e` (3 tests skipped without test credentials)

#### Phase 9 — Identity and account foundation (in progress)

- Added a real profile/settings surface at `/profile` and `/settings`.
- Added profile updates for name, occupation, and phone.
- Added authenticated password changes with current-password verification.
- Added explicit sign-out behavior that clears the local session.
- Added a signed Google OAuth authorization-state flow:
  `/api/v1/auth/google/login` and `/api/v1/auth/google/callback`.
- Added Google account provisioning by verified email and automatic login
  session creation.
- Added the frontend OAuth callback route and connected the login form to the
  backend Google flow.
- Added configuration for `FRONTEND_URL`, `GOOGLE_CLIENT_ID`,
  `GOOGLE_CLIENT_SECRET`, and `GOOGLE_REDIRECT_URI`.
- Google sign-in remains explicitly disabled until provider credentials are
  configured; the API returns a clear configuration error instead of a
  success-shaped fallback.

Validation completed:

- `cd frontend && npm run build`
- `python -m compileall backend\app`
- FastAPI application import and route registration
- Backend requirements installation including `httpx`

Next identity work:

- Add refresh-token rotation and server-side session/device management.
- Add email verification, recovery email delivery, and account deletion.
- Add provider identity metadata and organization/workspace membership.
- Add security activity, login history, and configurable notification/privacy
  settings.

### Dashboard onboarding

- Returning users see recent documents ordered by their last visited activity.
- New users see a getting-started panel instead of blank Recent and Activity sections.
- New users can browse templates, create a page, create a whiteboard, or create a space.

### Pages and whiteboards

- Pages and whiteboards open in read-only mode after login or re-login.
- Users must select **Edit** before changing content or titles.
- **Update** explicitly saves the current draft and returns the document to read-only mode.
- **Publish** saves the page or whiteboard and marks it as published.
- Page editing includes active Bold, Italic, Underline, and strikethrough states; paragraph/heading/quote/code styles; ordered and unordered lists; left/center/right alignment; an expanded text and highlight colour palette; grouped searchable emoji picker; styled tables; tabs; info panels; mentions; links; image/video URL insertion; and image file upload.
- Formatting selections are preserved when a toolbar control or popover is clicked. Link, media, colour, emoji, insert, and slash-command windows close when the user clicks elsewhere or presses Escape.
- Whiteboards retain their existing drawing, selection, table, text, sticky-note, pan, zoom, undo, and redo tools while preventing mutations until Edit is selected.

The frontend build is verified with:

```bash
cd frontend
npm run build
```

#### Phase 10 — Organizations, workspaces, members, and tenant administration (in progress)

- Added SQLAlchemy tenant tables for organizations, workspaces, workspace
  memberships, and expiring single-use invitations.
- Added explicit tenant roles: owner, admin, member, and viewer.
- Added authenticated workspace listing and workspace creation.
- Added workspace member listing, role changes, invitation creation, and
  invitation acceptance with email matching and expiry enforcement.
- Added invitation resend and revoke endpoints.
- Added workspace ownership transfer with organization-owner synchronization.
- Added tenant audit events for workspace creation, invitation creation,
  invitation revocation, and ownership transfer.
- Added workspace-scoped MongoDB document metadata and dashboard filtering.
- Existing owner-owned spaces and pages are backfilled into the selected
  workspace on first workspace load without changing their content or sharing.
- Legacy users without a tenant are automatically given a personal
  organization and workspace, so Invite Fellow works immediately after login.
- New document creation rejects workspace IDs the authenticated user cannot
  access.
- Added a workspace administration page at `/settings/workspaces` for
  creating organizations/workspaces, inviting members, and managing roles.
- Kept existing personal spaces and document-level sharing compatible while the
  next tenant step associates MongoDB spaces with a selected workspace.
- Removed the redundant FAQ/help and settings icons from the dashboard header;
  profile remains the single account entry point.
- Removed the unused Customize sidebar action and its controls.
- Updated Invite Fellow to create a workspace invitation and open a prefilled
  email containing the invitation link.
- Added the invitation landing page at `/invite/:token`.

Validation completed:

- `python -m compileall backend\app`
- FastAPI import and tenant route registration (`45` routes)
- `cd frontend && npm run build`
- `git diff --check`
- `cd frontend && npm run test:e2e` (Phase 10 tenant shell coverage; requires
  `E2E_USERNAME` and `E2E_PASSWORD`)

Next tenant work:

- Add workspace context to spaces and page creation.
- Add invitation and audit history views to the administration page.
- Add organization-level security settings.
- Add authenticated browser coverage for workspace creation and role denial.

#### Workspace navigation polish

- Workspace and page views now retain the primary dashboard navigation:
  For you, Templates, Recent, Favourite Projects, and All Projects.
- The navigation appears above the current space/page tree instead of replacing
  the dashboard experience; the duplicate Dashboard button was removed because
  the workspace header already provides that route.
- Space views now keep the sidebar visible, with the active space and its
  content shown beneath the primary navigation.
- Navigating to a child page now automatically keeps its ancestor pages
  expanded in the tree.
- New child pages are created as `Untitled` so users can name them directly.
- Template content now stays isolated to the page created from that template;
  switching between pages remounts the editor for the active document instead
  of reusing stale content from the previous page.
- Workspace sidebar navigation now opens the corresponding dashboard view:
  Recent, Favourite Projects, All Projects, and Templates no longer all open
  the default dashboard state.
- Workspace navigation now opens those flyouts in place without leaving the
  current page or space. Dashboard and workspace navigation use matching
  sidebar width, button height, padding, and text sizing.
- Workspace navigation now mirrors dashboard controls: “For you” links to the
  dashboard, while Recent, Favourite Projects, All Projects, and Templates
  use trailing chevrons and active flyout states.
- Dashboard and workspace notification bells now share the same notification
  feed, unread indicator, read-state behavior, and notification panel. The
  workspace header no longer displays the redundant people icon.
- Dashboard Feed activity now loads persisted per-document activity from the
  collaboration API, orders it by newest event, links each event to its page,
  and refreshes live every 15 seconds. Discover actions now open the existing
  Templates or All Projects flyouts instead of being inert buttons.
- Dashboard workspace selection now validates the locally stored workspace ID
  against the authenticated user’s workspace memberships before requesting
  documents. Stale or revoked workspace IDs are cleared, and 403 membership
  errors are no longer incorrectly reported as MongoDB outages.
- Authentication failures are now handled centrally: a protected API `401`
  clears the stale local session and redirects to login, while protected routes
  also require an access token instead of trusting only cached user metadata.
  This prevents an expired token from leaving the dashboard visible while all
  document and workspace requests fail.
- Page editing now follows Confluence-style keyboard actions: `E` enters edit
  mode, `Ctrl/Cmd+S` updates the draft, and `Ctrl/Cmd+Enter` publishes (or
  unpublishes) the page. The buttons expose the same shortcuts visually and
  through `aria-keyshortcuts`, while typing in form fields or the editor does
  not trigger the edit shortcut.
- Read-only page content now requires an explicit confirmation before editing:
  double-clicking the content opens a “Would you like to edit this page?”
  dialog, and only “Yes, edit” enables the editor. Escape and “No” leave the
  page read-only.
- Workspace titles now support fast renaming: double-clicking a title enters
  title-edit mode and selects the complete name, while the sidebar Rename
  action preselects the full existing name. Pressing Enter commits the title
  change once and stops the event from affecting page editing shortcuts.
- Unsaved edits now persist as per-document local drafts across workspace
  navigation and reloads. Text pages and whiteboards restore a draft only when
  it is newer than the server version, while successful Update, Publish,
  history restore, archive, and delete operations clear the local draft.
- Deleting the active file from the workspace sidebar now keeps navigation
  inside the workspace: it opens the parent page, a remaining sibling, or the
  containing space instead of always redirecting to the dashboard.
- The workspace sidebar’s existing “Create new” button now opens the same
  creation menu and uses the same page, whiteboard, space, and template
  creation flows as the header Create button. Its original compact sidebar
  appearance is preserved, with the menu opening upward to remain visible.
- The workspace sidebar creation menu now floats between the sidebar and the
  workspace content instead of being constrained inside the sidebar. It is
  aligned to the existing button and remains upward-opening and accessible
  without changing the button’s appearance.
- File action menus opened from the workspace sidebar three-dot controls now
  float outside the sidebar. They align to the left edge of the action button,
  open downward for items with room below, and automatically open upward with
  bottom-left alignment near the bottom of the list.
- Dashboard Recent Activities now includes the user’s recently visited files,
  even when no separate activity event exists, and labels those fallback
  entries as recently opened. The Discover something new panel no longer
  displays the redundant See all button.
- Workspace editing shortcuts and title controls now apply consistently to
  Silo pages, Sketch whiteboards, Shed documents, and Stead spaces. Each
  supports E to edit, Ctrl/Cmd+S to update, Ctrl/Cmd+Enter to publish or
  unpublish, double-click title selection, and Enter-to-commit title changes.
  Stead plan controls also remain read-only until Edit mode is enabled.
- Every workspace sidebar file row now has a plus create action. Its floating
  Confluence-style menu supports Live Doc, Page, Whiteboard, Database, Smart
  Link, and Folder actions, creating the corresponding Silos document or
  container in the current workspace context.