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

docker compose up -d

2. Backend

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

cd frontend
npm install
npm run dev

• Landing page: http://localhost:5173
• Login page: http://localhost:5173/login
• API 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:

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 menu uses the native Silos names: Silo, Stead, Sketch, and Shed. Silo, Sketch, and Shed creations inherit the selected file's workspace and become tree children of that file; Stead follows the existing space setup flow.