383 lines
18 KiB
Markdown
383 lines
18 KiB
Markdown
# 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
|
||
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.
|