How papra-hq/papra works
Project type and purpose
• Papra is a full-stack, monorepo document management and archiving platform.
• It contains:
• A static documentation site (Astro)
• A web client (SolidJS)
• A backend API server (HonoJS + Drizzle ORM)
• Auxiliary packages: CLI tool, API-SDK, “lecture” extractors, webhooks handler
File structure
• Top-level:
• apps/docs → static documentation site
• apps/papra-client → frontend SPA
• apps/papra-server → backend REST API + workers + scheduled tasks
• packages/cli → command-line interface
• packages/api-sdk → TypeScript SDK for the API
• packages/lecture → document content extraction engines
• packages/webhooks → standalone webhook processing library
• Monorepo managed by pnpm-workspace.yaml, CI via GitHub Actions, Dockerfiles for containerization
Key architectural patterns
• Client-server separation: SPA front end communicates via REST/JSON.
• Layered backend:
• HTTP routes → middlewares (CORS, auth, errors) → use cases → services → repositories → database or storage
• Pluggable drivers: document storage drivers (FS, S3, Azure Blob), email ingestion drivers (Owlrelay, catch-all), task drivers (memory, libsql).
• Scheduled tasks and background jobs for: text extraction, hard-delete purging, invitation expiration.
• External integration points: email service providers, object storage, database hosting, webhook targets.
Main components & interactions
A. Frontend (apps/papra-client)
• UI built with SolidJS, communicates over HTTPS to Papra API
• Localization, theming, document upload UI, search, tagging rules UI
B. Backend API (apps/papra-server)
• HTTP server (Hono) with route modules: auth, documents, organizations, tags, webhooks, ingestion-folders, intake-emails, subscriptions, etc.
• Business logic (usecases) and data layer (Drizzle ORM → relational database)
• Drivers for document storage (S3, Azure Blob, local FS)
• Drivers for email ingestion and username generation
• Scheduled tasks (cron-style or triggered on startup) for content extraction and cleanup
C. Database
• Relational database (PostgreSQL via Drizzle)
• Core tables: users, organizations, documents, tags, api-keys, invitations, ingestion_folders, subscriptions, document_activity_log, etc.
D. Storage
• Pluggable storage backends for document files
• Encryption service for file content
E. External services
• Email drivers (SMTP, Resend, logger) for transactional emails
• Third-party storage (S3, Azure)
• Webhooks (outgoing) to notify external systems
F. CLI & SDK
• CLI (packages/cli) calls the API to manage docs, ingest files, generate Docker compose, etc.
• API-SDK (packages/api-sdk) wraps HTTP client for third-party apps