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.
- 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.

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.