# papra-hq/papra architecture

> Architecture diagram of the GitHub repository papra-hq/papra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/papra-hq/papra
- Repository: https://github.com/papra-hq/papra

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        Docs["Static Docs Site (Astro)"]:::client
        Browser["Browser (Papra-Client SPA)"]:::client
        CLI["CLI Tool"]:::client
        SDK["API-SDK"]:::client
    end

    %% Backend
    subgraph "Papra Backend"
        subgraph "Routes Layer"
            Index["HTTP Server\n(index.ts, server.ts)"]:::routes
            Middlewares["Global Middlewares"]:::routes
            AuthRoute["Authentication Module\n(auth.routes.ts)"]:::routes
            DomainRoutes["API Routes\n(*.routes.ts)"]:::routes
        end
        subgraph "Business Logic"
            Usecases["Usecases\n(*.usecases.ts)"]:::usecases
        end
        subgraph "Services Layer"
            Services["Services\n(*.services.ts)"]:::services
        end
        subgraph "Persistence Layer"
            Repos["Repositories\n(*.repository.ts)"]:::repo
            Migrations["Migrations"]:::data
            DB["Database Core\n(database module)"]:::data
        end
        subgraph "Storage Drivers"
            FS["Local FS Driver"]:::drivers
            S3["S3 Driver"]:::drivers
            AZ["Azure Blob Driver"]:::drivers
            Mem["In-Memory Driver"]:::drivers
            Encrypt["Encryption Service"]:::services
        end
        subgraph "Email Drivers"
            SMTP["SMTP Driver"]:::drivers
            Resend["Resend Driver"]:::drivers
            Logger["Logger Driver"]:::drivers
        end
        subgraph "Ingestion & Intake"
            IngestFolders["Ingestion Folders"]:::services
            IntakeEmails["Intake Emails"]:::services
        end
        subgraph "Webhooks Module"
            WebhookModule["Webhooks (outgoing)"]:::services
        end
        subgraph "Scheduled Tasks"
            DocTasks["Document Tasks"]:::tasks
            OrgTasks["Organization Tasks"]:::tasks
        end
    end

    %% External Services
    subgraph "External Services"
        StorageSvc["Object Storage\n(S3/Azure)"]:::external
        EmailSvc["Email Providers"]:::external
        WebhookTargets["Webhook Targets"]:::external
    end

    %% Connections
    Docs -->|HTTPS/JSON| Index
    Browser -->|HTTPS/JSON| Index
    CLI -->|HTTPS/JSON| Index
    SDK -->|HTTPS/JSON| Index

    Index --> Middlewares
    Middlewares --> AuthRoute
    Middlewares --> DomainRoutes

    AuthRoute -->|uses| Usecases
    DomainRoutes -->|uses| Usecases

    Usecases -->|calls| Services
    Services -->|reads/writes| Repos
    Repos -->|queries| DB
    Migrations -->|migrates| DB

    Services --> FS
    Services --> S3
    Services --> AZ
    Services --> Mem
    Services --> Encrypt

    Services --> SMTP
    Services --> Resend
    Services --> Logger

    Services --> IngestFolders
    Services --> IntakeEmails
    Services --> WebhookModule

    Usecases --> DocTasks
    Usecases --> OrgTasks

    FS -->|stores files| StorageSvc
    S3 -->|stores files| StorageSvc
    AZ -->|stores files| StorageSvc

    SMTP -->|sends email| EmailSvc
    Resend -->|sends email| EmailSvc
    Logger -->|logs email| EmailSvc

    WebhookModule -->|POST| WebhookTargets

    DocTasks -->|invokes| Services
    OrgTasks -->|invokes| Services

    %% Click Events
    click Docs "https://github.com/papra-hq/papra/tree/main/apps/docs"
    click Browser "https://github.com/papra-hq/papra/tree/main/apps/papra-client"
    click CLI "https://github.com/papra-hq/papra/tree/main/packages/cli"
    click SDK "https://github.com/papra-hq/papra/tree/main/packages/api-sdk"
    click Index "https://github.com/papra-hq/papra/blob/main/apps/papra-server/src/index.ts"
    click Index "https://github.com/papra-hq/papra/blob/main/apps/papra-server/src/modules/app/server.ts"
    click Middlewares "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/app/middlewares"
    click AuthRoute "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/app/auth"
    click DomainRoutes "https://github.com/papra-hq/papra/blob/main/apps/papra-server/src/modules/*/*.routes.ts"
    click Usecases "https://github.com/papra-hq/papra/blob/main/apps/papra-server/src/modules/*/*.usecases.ts"
    click Services "https://github.com/papra-hq/papra/blob/main/apps/papra-server/src/modules/*/*.services.ts"
    click Repos "https://github.com/papra-hq/papra/blob/main/apps/papra-server/src/modules/*/*.repository.ts"
    click DB "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/app/database"
    click Migrations "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/migrations"
    click FS "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/documents/storage/drivers/fs"
    click S3 "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/documents/storage/drivers/s3"
    click AZ "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/documents/storage/drivers/az-blob"
    click Mem "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/documents/storage/drivers/memory"
    click Encrypt "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/documents/storage/encryption"
    click DocTasks "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/documents/tasks"
    click OrgTasks "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/organizations/tasks"
    click SMTP "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/emails/drivers"
    click Resend "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/emails/drivers"
    click Logger "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/emails/drivers"
    click IngestFolders "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/ingestion-folders"
    click IntakeEmails "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/intake-emails"
    click WebhookModule "https://github.com/papra-hq/papra/tree/main/apps/papra-server/src/modules/webhooks"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6
    classDef routes fill:#FFE5B4,stroke:#FF8C00
    classDef usecases fill:#E6E6FA,stroke:#9370DB
    classDef services fill:#DFFFD6,stroke:#32CD32
    classDef repo fill:#F5DEB3,stroke:#DAA520
    classDef drivers fill:#E0FFFF,stroke:#20B2AA
    classDef data fill:#FFFACD,stroke:#FFD700
    classDef tasks fill:#FFD1DC,stroke:#FF1493
    classDef external fill:#F0F0F0,stroke:#A9A9A9
```
