Project Documentation - Overview

Project Overview

Purpose and Scope

Outline is a team-based knowledge management and document collaboration platform designed to enable secure creation, organization, sharing, and viewing of documents within and outside organizations. It addresses the need for efficient content management and seamless collaboration through integrated workflows and extensible sharing features.

Key Features and Modules

• Document Creation and Editing: Support for rich text and markdown editing with features like templates, backlinks, and real-time collaboration.
• Collections: Organizational units for grouping documents, with configurable overviews and recent item views.
• Sharing and Access Control: Fine-grained permissions for sharing documents publicly or within teams, including nested document shares and support for custom and branded domains.
• Authentication and Authorization: Robust user authentication with OAuth 2.0 flows, secure token management, and permission policies enforced on backend services.
• Integrations: Embedding content from external services (GitHub, GitLab, Dropbox, Pinterest) and Slack integration for knowledge base search and link previews.
• Backend Services: Modular backend comprising Web, Worker, Websockets, Collaboration, and Admin services, facilitating scalable deployments including Docker environments.
• Analytics and SEO: Tracking of share usage metrics and server-side rendering optimized for SEO and social media link unfurling.

User-Facing Capabilities and Backend Services

• Responsive frontend with React and Vite providing a seamless document viewing, editing, and navigation experience.
• Backend APIs handling document CRUD operations, sharing logic, user management, authentication, and integration endpoints.
• Real-time collaboration enabled by websockets and asynchronous queue processing for background tasks.

Page Routes and API Endpoints

• Multiple page routes for home, document views, collection overviews, document creation, user drafts, archives, trash, and OAuth authorization.
• API endpoints include health checks, OAuth authorization/token management, content retrieval, and embedding services.
• Public sharing routes supporting custom domains and share links for documents and nested content.

Integrations and Extensibility Points

• Supports rich embedding of third-party content such as GitHub repositories, GitLab projects, Dropbox files, and Pinterest boards.
• Fully featured RPC-style API accessible via OAuth tokens enables programmatic management of documents, collections, and users.
• Slack integration offers slash commands and link previews to enhance collaboration workflows.
• Supports custom branding on shared content, including team-specific logos, favicons, and domain white-labeling.

Support for Different User Roles

• End Users: Seamless authoring, browsing, searching, and consuming of knowledge base content.
• Team Administrators: Manage collections, sharing policies, user roles, and integrations.
• Developers: Extend functionality via API, integrate with external services, contribute to open source.
• DevOps/Engineers: Deploy and maintain backend services with modular configuration and containerized setups.
• Product Owners and Managers: Oversee feature development, user adoption, and security compliance.
• Security Professionals: Enforce access controls, monitor sharing policies, and ensure responsible vulnerability reporting.

Technologies and Architectural Style

• Monorepo project structured into frontend (React with MobX and Styled Components) and backend (Koa, Sequelize ORM, Redis, Bull queues).
• Shared codebase for utilities and UI components improves maintainability.
• Modular backend services support flexible deployment and scaling.
• Strong emphasis on code style, testing, continuous integration, and secure coding practices.

Additional Notable Aspects

• Supports nested sharing of documents with robust authorization and audit trails.
• Facilitates desktop-application authentication continuity through dedicated redirect routes.
• Emphasizes user experience with loading placeholders, retry mechanisms, and SEO-friendly metadata.
• Provides comprehensive onboarding and documentation for users, developers, and administrators to lower the learning curve and foster community contributions.

Functional Flows Summary

This section provides an overview of the known functional flows within the project. These cover typical user interactions and backend operations, often linked to specific routes or API endpoints.

Flow Name	Flow Type	Route or API Path	Short Description
Landing or home page	Page	/	The main entry point for users, providing access to general content or navigation within the application.
Display or edit specific document by slug	Page	/doc/${slug}	Allows users to view or edit a particular document identified by a unique slug.
New document or resource creation interface	Page	/create	Interface for users to create new documents or resources within the platform.
User logout endpoint	Page	/logout	Endpoint that logs out the current user and ends their session.
Redirect for desktop app authentication	Page	/desktop-redirect	Handles redirection during desktop app authentication flows.
OAuth 2.0 authorization grant page	Page	/oauth/authorize	User interface for granting OAuth 2.0 authorization to third-party applications.
View shared document by share ID	Page	/s/:shareId	Allows anonymous or authenticated users to view documents shared publicly via a unique share ID.
Shared document view with slug	Page	/s/:shareId/doc/${slug}	Displays a shared document identified by both share ID and document slug for secure public access.
Access user drafts	Page	{draftsPath()}	Provides the user interface for viewing and managing their document drafts.
View archived documents or resources	Page	{archivePath()}	Displays documents or resources that have been archived by the user or team.
Access trashed or deleted items	Page	{trashPath()}	Allows users to view and manage items that have been moved to trash or deleted.
User home page with tabbed interface	Page	{${homePath()}/:tab?}	User dashboard page supporting optional tab views for organizing recent, created, or favorite documents.
Create a new document in a collection	Page	/collection/:id/new	Page for creating new documents inside a specified collection.
Collection detail view with tabs	Page	/collection/:id/:tab?	Displays collection details and supports tabbed navigation for sorting or filtering.
New document creation page	Page	/doc/new	Dedicated page to begin creating a new document, optionally with templates or pre-filled content.
Alternate document view by slug	Page	/d/${slug}	Alternative route to view a document specified by slug, possibly for public or embedded views.
View document revision history	Page	/doc/${slug}/history/:revisionId?	Displays historical versions of a document for review or rollback.
Show document insights and analytics	Page	/doc/${slug}/insights	Presents analytics and insights about document usage and engagement.
Edit document interface	Page	/doc/${slug}/edit	Provides the editing UI for modifying the contents of a document.
Document read/view page	Page	/doc/${slug}	Main read-only view for a specific document accessible by authenticated or public users.
Search documents with optional query	Page	{${searchPath()}/:query?}	Supports search functionality over documents with optional query parameters.
404 Not Found error page	Page	/404	Displays an error page when content is not found or invalid routes are accessed.
Health check API endpoint	API	GET /_health	Provides system health status for monitoring and automated checks.
General API information or endpoint root	API	GET /api	Serves as the root or informational endpoint for API consumers.
POST API root for creating resources	API	POST /api	Endpoint for creating resources programmatically via POST requests.
Authentication redirect endpoint	API	GET /auth/redirect	Redirects users during authentication flows to appropriate endpoints or pages.
OAuth 2.0 authorization submission	API	POST /oauth/authorize	Handles authorization requests submitted by clients during OAuth 2.0 flows.
OAuth token exchange endpoint	API	POST /oauth/token	Endpoint to exchange OAuth authorization codes for access tokens.
OAuth token revocation endpoint	API	POST /oauth/revoke	Revokes OAuth tokens to invalidate access permissions.
Serve static assets	API	GET /static/*	Serves static files like images, CSS, and JavaScript assets.
Localization files per language	API	GET /locales/:lng.json	Provides translation files in JSON format for different languages.
Robots exclusion protocol file	API	GET /robots.txt	Serves the robots.txt file to instruct search engine indexing behavior.
OpenSearch descriptor file	API	GET /opensearch.xml	Provides OpenSearch configuration for browsers or clients supporting search integration.
Embed GitLab content service	API	GET /embeds/gitlab	Facilitates embedding of GitLab-hosted content within documents.
Embed GitHub content service	API	GET /embeds/github	Facilitates embedding of GitHub-hosted content within documents.
Embed Dropbox content service	API	GET /embeds/dropbox	Facilitates embedding of Dropbox-hosted content within documents.
Embed Pinterest content service	API	GET /embeds/pinterest	Facilitates embedding of Pinterest hosted content within documents.

Project Functional Architecture Overview

• User Interface (Frontend) Pages

  • The application offers a variety of pages including landing, document viewing (/doc/:slug), document creation (/doc/new and /collection/:id/new), user home with tabs (/home/:tab?), and shared document views via share links (/s/:shareId) or nested shared documents (/s/:shareId/doc/:slug).
  • These pages support tasks such as creating, viewing, editing, sharing, and searching documents, managing collections, drafts, archives, and trash, and provide interfaces for authentication (login/logout) and OAuth authorization.
  • Special pages exist for managing recently created and updated documents, enhancing user productivity and document lifecycle tracking.

• Backend API Endpoints

  • The backend exposes RESTful API endpoints, such as health checks (GET /_health), general API roots (GET /api, POST /api), authentication redirects (GET /auth/redirect), and OAuth flows (POST /oauth/authorize, /oauth/token, /oauth/revoke).
  • Document and share data are served and manipulated through endpoints like GET /doc/:documentSlug and share routes such as GET /s/:shareId and GET /s/:shareId/doc/:documentSlug.
  • Static assets and localization files are served via GET /static/* and GET /locales/:lng.json.

• Sharing and Collaboration Features

  • The platform supports secure public sharing of documents via unique share links and custom branded domains or subdomains, enabling external users to view documents without authentication.
  • Shares support analytics tracking for usage, view counts, and last accessed timestamps, while enforcing permissions and team-defined sharing policies.
  • Documents may be shared individually or as nested sets (child documents), with server-side rendering for SEO and social media link unfurling.
  • Public sharing integrates team branding (names, logos) and allows embedding of shared content in iframes by relaxing security headers accordingly.

• Authentication and Authorization

  • The system implements OAuth 2.0 authorization flows, including authorization grants, token exchange, and token revocation endpoints to facilitate third-party authorized access securely.
  • Token-based authentication supports JWTs, OAuth tokens, and API keys with role-based access control and token validation middleware enforcing permissions and session handling.
  • Post-login redirection logic routes users to appropriate team homepages or collections based on access and usage context, enhancing user experience.

• Integration Points and Supported External Services

  • The platform integrates third-party content embeddings from services like GitHub, GitLab, Dropbox, and Pinterest, directly embedding external resources into documents.
  • Analytics integrations are supported per team to track document and share page views, feeding into usage metrics and monitoring.

• Document Management Features

  • Documents can be organized into collections, with support for managing drafts, archives, and trash, accessible via dedicated frontend routes.
  • Historical document views and insights are available through specific pages showing revision history and analytics.
  • The system supports creating new documents from templates, associating them with collections or parent documents, facilitating structured content creation workflows.

• Typical User Flows Supported

  • Users can create new documents or collections, view and edit existing documents, and share documents securely with external collaborators through public links or branded domains.
  • Searching documents with optional queries is supported to facilitate quick content retrieval.
  • Managing personal document lists such as recently created, recently updated, or recently viewed documents boosts productivity.
  • The sharing flows ensure view counts and analytics update as documents are accessed, with mechanisms preventing unauthorized or expired access.

• Custom Domains, Public Sharing, and Branded Sharing Features

  • The system supports custom domain usage allowing teams to serve shared content under their own branded URLs.
  • Public sharing can be branded with team names, descriptions, and icons, reflected in metadata and favicon for shared document views.
  • SEO and indexing controls allow selective search engine visibility based on share settings, improving content discoverability and privacy balance.
  • The infrastructure supports embedding shared documents transparently into other websites or applications via iframe allowance and proper security policy handling.

In summary, the project organizes its functionalities into a cohesive, team-centric knowledge management platform combining a rich React frontend with a robust Koa backend API. It emphasizes secure document collaboration and sharing, fine-grained access control, user-friendly workflows for document lifecycle management, seamless integration of external content and analytics, and flexible branding and domain routing capabilities that serve both internal users and external collaborators efficiently.

Summary of Key Pages and Features

Below is a listing of key user-facing pages and their primary roles and business purposes.

• Page or Route path: /
  Purpose: Landing or home page serving as the main entry point for the application.
  Major actions supported: User onboarding, navigation to other pages such as documents or collections.
  Workflow: Users arrive to start their session or select other areas to explore.

• Page or Route path: /home
  Purpose: Personalized dashboard showing recently viewed documents.
  Major actions: View recently accessed documents, navigate to document details.
  Workflow: Fetch and display paginated list of recent documents with appropriate UI hints.

• Page or Route path: /home/recent
  Purpose: Displays a list of recently updated documents for quick access to fresh content.
  Major actions: Fetch recent updates, paginate and display documents.
  Workflow: System queries documents by recent updates; users browse list.

• Page or Route path: /home/created
  Purpose: Allows users to see and manage documents they have personally created.
  Major actions: Fetch and view paginated list of created documents, including collections.
  Workflow: Retrieve user’s documents and display; handle empty states gracefully.

• Page or Route path: /create
  Purpose: Interface to initiate creation of new documents or resources.
  Major actions: Start a new document or resource flow.
  Workflow: User triggers creation, guided to document setup or editing.

• Page or Route path: /doc/new
  Purpose: New document creation page allowing users to create documents with optional collection or parent links and templates.
  Major actions: Create document, optionally apply template, set metadata, publish or save draft, redirect to editor/viewer.
  Workflow: On access, parameters parsed and new document created; placeholder shown during creation; finally redirected.

• Page or Route path: /doc/${slug}
  Purpose: Shared document viewer enabling access to a document via unique slug for collaboration or public sharing.
  Major actions: Fetch and render the document content.
  Workflow: Load document lazily with retries; render for read-only display.

• Page or Route path: /doc/${slug}/edit
  Purpose: Document editing interface to modify existing documents.
  Major actions: Load editable document component, support lazy loading with retry.
  Workflow: Render editing UI to user after component loads.

• Page or Route path: /doc/${slug}/history/:revisionId?
  Purpose: View revision history for a document to track changes over time.
  Major actions: Display historical versions, enable comparison or restore.
  Workflow: User selects revisions; history is fetched and shown.

• Page or Route path: /doc/${slug}/insights
  Purpose: Provide in-depth insights and analytics for a given document.
  Major actions: Load analytics component, display document metadata/usage stats.
  Workflow: Lazy load insights UI; display comprehensive document analysis.

• Page or Route path: /collection/:id/new
  Purpose: Create a new document inside a specific collection or as a child document.
  Major actions: Fetch collection, create linked document, handle templates and titles, publish or draft, redirect to editor/viewer.
  Workflow: Parse parameters, create document linked to collection, show placeholder during process.

• Page or Route path: /collection/:id/:tab?
  Purpose: Collection detail view supporting tabs such as recent, overview, or published documents.
  Major actions: Show documents filtered by tab, navigate between tabs.
  Workflow: Load collection data; render according to active tab.

• Page or Route path: {draftsPath()}
  Purpose: Display user’s drafts for managing unfinished or in-progress documents.
  Major actions: Fetch drafts, allow selection and editing.
  Workflow: Lazy load drafts page; present drafts with retry for robustness.

• Page or Route path: {archivePath()}
  Purpose: Access archived documents for review or retrieval.
  Major actions: Display archived documents list with context like parent docs; support pagination.
  Workflow: Fetch archived docs for collection; render sorted list.

• Page or Route path: {trashPath()}
  Purpose: Manage items marked for deletion or trash.
  Major actions: View and restore or permanently delete trashed items.
  Workflow: List trash items; enable recovery actions.

• Page or Route path: {searchPath()}/:query?
  Purpose: Search page to find documents by query.
  Major actions: Accept search queries, display results.
  Workflow: Query backend; render search results dynamically.

• Page or Route path: /s/:shareId
  Purpose: Publicly shared document view accessible via share ID, supporting anonymous access.
  Major actions: Validate share, increment view count, render document with branding.
  Workflow: Load share and document; update analytics; render HTML view.

• Page or Route path: /s/:shareId/doc/${slug}
  Purpose: View specific shared document under a share link.
  Major actions: Load specific shared document, check permissions, update metrics, render.
  Workflow: Middleware determines share context; loads document; renders with branding and analytics.

• Page or Route path: /logout
  Purpose: Endpoint to log out the current authenticated user.
  Major actions: Clear authentication session, redirect to a safe page.
  Workflow: User triggers logout; session cleared; redirect occurs.

• Page or Route path: /oauth/authorize
  Purpose: OAuth 2.0 authorization grant interface for third-party app authorization.
  Major actions: Display consent UI, handle authorization codes.
  Workflow: User grants or denies permission; tokens issued accordingly.

• Page or Route path: /desktop-redirect
  Purpose: Redirect endpoint to facilitate desktop app authentication flow.
  Major actions: Redirect users from web to desktop app authentication.
  Workflow: Validate request; redirect to desktop client.

• Page or Route path: Various asset and static paths (e.g., /static/*, /locales/:lng.json, /robots.txt, /opensearch.xml)
  Purpose: Serve static files like localization, assets, SEO files.
  Major actions: Deliver static content efficiently.
  Workflow: Requests routed to file server or static content handlers.

API Endpoint Overview

This section summarizes important backend API endpoints and their main use cases.

HTTP Method	Path	Main Operations	Authentication / Authorization Notes	Special Behaviors or Requirements
GET	/_health	Health check endpoint - verifies database and Redis connectivity	No authentication required	Returns "OK" if services reachable; HTTP 500 if any check fails
GET	/api	General API root information	Varies based on API design	Handles unknown or catch-all API queries with appropriate errors
POST	/api	Create resources via API	Requires authentication and authorization	Acts as catch-all for undefined POST endpoints, returns 404 if not found
GET	/auth/redirect	Token-based user authentication and redirect	Requires valid access token or session	Redirects user post-login to appropriate team or collection page
POST	/oauth/authorize	OAuth 2.0 client authorization code issuance	Requires authenticated user and client authorization	Uses rate limiting; enforces CSRF protection; supports redirects and JSON
POST	/oauth/token	OAuth 2.0 access token and refresh token generation	Requires client authentication (client credentials)	Includes rate limiting; returns tokens with scopes and expiration
POST	/oauth/revoke	OAuth token revocation	Requires client authentication	Complies with RFC 7009; always returns success even if token invalid
GET	/static/*	Serves static assets (JS, CSS, images)	No authentication required	Long-term caching headers; returns 400 (not 404) if file missing
GET	/locales/:lng.json	Provides localization JSON files for supported languages	No authentication required	Caching enabled; returns 404 if language not supported
GET	/robots.txt	Robots exclusion protocol file	No authentication required	Static file delivery
GET	/opensearch.xml	OpenSearch descriptor file	No authentication required	Static file delivery
GET	/embeds/gitlab	GitLab content embed service	No authentication required	Embeds GitLab content for integration
GET	/embeds/github	GitHub content embed service	No authentication required	Embeds GitHub content for integration
GET	/embeds/dropbox	Dropbox content embed service	No authentication required	Embeds Dropbox content for integration
GET	/embeds/pinterest	Pinterest content embed service	No authentication required	Embeds Pinterest content for integration
GET	/doc/:documentSlug	Retrieves and renders shared documents by slug	Public access if shared; authorization checks apply	Supports custom domains, SEO metadata, analytics; handles nested shares
GET	/s/:shareId	Shared document viewing via share ID	Public access controlled by share permissions	Updates view counts; allows embedding; enforces share status and access
GET	/s/:shareId/doc/:documentSlug	Shared document viewing with document slug	Public access controlled by share permissions	Detailed share and team context resolution; analytics integration
GET	/s/:shareId/*	Shared document and nested content viewing	Public access controlled by share permissions	Supports custom domains and subdomains; SEO and branding applied

Integration and Extensibility

• Supported Third-Party Content Embeds:

  • GitHub (GET - /embeds/github): Renders embedded GitHub repositories, files, or gists seamlessly within the application.
  • GitLab (GET - /embeds/gitlab): Embeds GitLab content such as repositories and commits without leaving the platform.
  • Dropbox (GET - /embeds/dropbox): Integrates Dropbox files and folders directly into the user interface for easy access.
  • Pinterest (GET - /embeds/pinterest): Displays Pinterest pins, boards, and related content inline via embedded views.

• API Usage for Programmatic Access and Automation:

  • A comprehensive REST API exposing endpoints for document creation, retrieval, sharing, and searching.
  • OAuth 2.0 protected API access allowing secure programmatic interactions with user data.
  • Endpoints such as /api, /oauth/authorize, /oauth/token, and /oauth/revoke facilitate authentication workflows and resource management.

• OAuth 2.0 Flows Supported:

  • Authorization (POST - /oauth/authorize): Implements the authorization code grant flow with rate limiting, CSRF protection, and scope validation.
  • Token Exchange (POST - /oauth/token): Issues access and refresh tokens with strict compliance and rate limiting safeguards.
  • Token Revocation (POST - /oauth/revoke): Allows clients to revoke access or refresh tokens securely, supporting compliance with RFC 7009.

• Messaging Integrations:

  • Slack and other messaging platform integration enable in-app document linking and search capabilities (though specific flow details are not provided, messaging integrations support enhanced collaboration and content discovery within team communication channels).

• Custom Domain and Branding Support:

  • The platform supports custom domains for public sharing of documents and collections.
  • Branded content sharing enables teams to apply their branding for external shared links, enhancing professional presentation and recognition.

• Extensibility and Customization Options:

  • Users can extend platform capabilities via API access and OAuth integration allowing third-party apps to interact with the system securely.
  • Embedding external content and the modular design of page routes and API endpoints support custom integrations or feature extensions by developers.
  • The system enforces access control and sharing policies while allowing configurable document workflows and team management features.

These capabilities collectively enable seamless integration of external content, secure API-driven automation, robust OAuth-based authorization, and flexible brandable sharing to support diverse user and developer needs.

Usage Context and Target Users

The project serves a diverse range of users and stakeholders, each benefiting from its features to improve collaboration, document management, and operational workflows:

• End Users / Knowledge Workers: These daily users create, view, edit, and search documents within the platform. The intuitive interface and robust sharing options enable them to collaborate effectively, maintain up-to-date knowledge bases, and streamline content access across teams.

• Team Administrators: Responsible for managing documents, collections, and user access, administrators leverage the platform’s organizational tools and sharing policies to enforce proper permissions, oversee content lifecycle (including drafts, archives, and trash), and maintain team-level branding and integrations.

• Developers and Contributors: Working on the project codebase, developers benefit from the modular architecture, OAuth 2.0 integration for secure API access, and extensibility points that support embedding external content (e.g., Dropbox, GitHub, GitLab). This facilitates customization, automation, and improvements aligned with evolving requirements.

• DevOps and Deployment Engineers: Handling infrastructure and services, these stakeholders rely on the project’s health check APIs, authentication flows, and environment configurations to deploy, monitor, and secure the application reliably in cloud-hosted or on-premises environments.

• Product Owners and Managers: Overseeing feature roadmaps and user experience, they use the platform’s analytics tracking on document shares, usage metrics, and collaboration workflows to prioritize enhancements and ensure the product meets organizational knowledge sharing goals.

• Security Professionals: Focused on access control and data protection, security teams utilize the platform’s fine-grained permission enforcement, token-based authentication methods, sharing revocation capabilities, and support for secure public sharing with domain validation to safeguard sensitive information.

Overall, the project’s functionalities are designed to serve these groups by enabling seamless creation, sharing, and management of documents; supporting secure, branded public sharing; facilitating integration with third-party content sources; and providing comprehensive authentication and authorization mechanisms—thereby enhancing workflows, collaboration, and organizational knowledge dissemination.