# theprismsystem/pluralscape-mono architecture

> Architecture diagram of the GitHub repository theprismsystem/pluralscape-mono, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theprismsystem/pluralscape-mono
- Repository: https://github.com/theprismsystem/pluralscape-mono
- Video tour (about a minute): https://gitdiagram.com/theprismsystem/pluralscape-mono/video

## Overview

Pluralscape is a privacy-focused plurality-management platform. A client sends authenticated REST or tRPC requests to the API; domain routes invoke services that read and write PostgreSQL-backed account, system, identity, fronting, communication, and sharing data. Clients also synchronize encrypted documents offline, while imports map external data through checkpointed persistence. The README documents mobile, encryption, sync, import, realtime, blob storage, and background-job capabilities; several are represented at subsystem level because their implementation was not sampled.

Main entry points: [`apps/api/src/routes/v1.ts`](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/v1.ts) (REST routes), [`apps/api/src/routes/trpc.ts`](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/trpc.ts) (tRPC routes), [`apps/api/src/services`](https://github.com/theprismsystem/pluralscape-mono/tree/main/apps/api/src/services) (Domain services), [`apps/api/src/index.ts`](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/index.ts) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API access"]
  node_api_entry["API server<br/>[index.ts]"]
  node_rest["REST routes<br/>[v1.ts]"]
  node_trpc["tRPC routes<br/>[trpc.ts]"]
end

subgraph group_domain["Plurality domains"]
  node_auth["Authentication<br/>[index.ts]"]
  node_account["Accounts and friends<br/>[index.ts]"]
  node_identity["System and identity<br/>[index.ts]"]
  node_fronting["Fronting and analytics<br/>[index.ts]"]
  node_communication["Communication<br/>[index.ts]"]
  node_privacy["Privacy and sharing<br/>[index.ts]"]
  node_services["Domain services"]
end

subgraph group_client["Client data"]
  node_sync_engine["Offline sync engine<br/>[sync-engine.ts]"]
  node_sqlite[("SQLite sync storage")]
  node_indexeddb[("Web sync storage")]
  node_crypto["Blob encryption<br/>[upload-pipeline.ts]"]
  node_key_storage[("Web key storage<br/>[web-key-storage.ts]")]
  node_import_core["Import orchestration<br/>[import-engine.ts]"]
  node_import_sp["Simply Plural import<br/>[import-engine.ts]"]
  node_query_client["Client query cache<br/>[query-client.ts]"]
end

subgraph group_operations["Platform operations"]
  node_pg[("PostgreSQL<br/>[db.ts]")]
  node_queue["Background jobs"]
  node_jobs["API job handlers<br/>[webhook-deliver.ts]"]
  node_blob_api["Blob API<br/>[index.ts]"]
  node_storage["Blob storage<br/>[storage.ts]"]
  node_realtime["Realtime notifications<br/>[sse-manager.ts]"]
  node_valkey[("Valkey")]
  node_s3[("S3-compatible storage")]
end

node_user(("User or client"))

node_user -->|"sends requests"| node_api_entry
node_api_entry -->|"dispatches REST"| node_rest
node_api_entry -->|"dispatches tRPC"| node_trpc
node_rest -->|"routes requests"| node_auth
node_rest -->|"routes requests"| node_account
node_rest -->|"routes requests"| node_identity
node_rest -->|"routes requests"| node_fronting
node_rest -->|"routes requests"| node_communication
node_rest -->|"routes requests"| node_privacy
node_trpc -->|"routes requests"| node_auth
node_trpc -->|"routes requests"| node_account
node_trpc -->|"routes requests"| node_identity
node_trpc -->|"routes requests"| node_fronting
node_trpc -->|"routes requests"| node_communication
node_trpc -->|"routes requests"| node_privacy
node_auth -->|"invokes services"| node_services
node_account -->|"invokes services"| node_services
node_identity -->|"invokes services"| node_services
node_fronting -->|"invokes services"| node_services
node_communication -->|"invokes services"| node_services
node_privacy -->|"invokes services"| node_services
node_services -->|"reads and writes"| node_pg
node_user -->|"uses client"| node_sync_engine
node_sync_engine -->|"stores encrypted changes"| node_sqlite
node_sync_engine -.->|"stores encrypted changes"| node_indexeddb
node_user -->|"prepares uploads"| node_crypto
node_crypto -.->|"uses keys"| node_key_storage
node_user -->|"starts import"| node_import_core
node_import_sp -->|"shares orchestration"| node_import_core
node_import_core -->|"persists mapped data"| node_pg
node_jobs -->|"uses job queue"| node_queue
node_blob_api -->|"requests blob operations"| node_storage
node_storage -.->|"stores blobs"| node_s3
node_realtime -.->|"uses pub-sub"| node_valkey
node_user -->|"uses client data"| node_query_client

click node_api_entry "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/index.ts"
click node_rest "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/v1.ts"
click node_trpc "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/trpc.ts"
click node_auth "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/auth/index.ts"
click node_account "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/account/index.ts"
click node_identity "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/systems/index.ts"
click node_fronting "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/fronting-sessions/index.ts"
click node_communication "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/messages/index.ts"
click node_privacy "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/buckets/index.ts"
click node_services "https://github.com/theprismsystem/pluralscape-mono/tree/main/apps/api/src/services"
click node_pg "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/lib/db.ts"
click node_sync_engine "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/sync/src/engine/sync-engine.ts"
click node_sqlite "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/sync/src/adapters/sqlite-storage-adapter.ts"
click node_indexeddb "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/mobile/src/platform/drivers/indexeddb-storage-adapter.ts"
click node_crypto "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/crypto/src/blob-pipeline/upload-pipeline.ts"
click node_key_storage "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/crypto/src/web-key-storage.ts"
click node_import_core "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/import-core/src/import-engine.ts"
click node_import_sp "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/import-sp/src/engine/import-engine.ts"
click node_queue "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/queue/src/adapters/bullmq/bullmq-job-worker.ts"
click node_jobs "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/jobs/webhook-deliver.ts"
click node_blob_api "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/blobs/index.ts"
click node_storage "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/lib/storage.ts"
click node_realtime "https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/lib/sse-manager.ts"
click node_query_client "https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/data/src/query-client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_entry,node_rest,node_trpc,node_user toneBlue
class node_auth,node_account,node_identity,node_fronting,node_communication,node_privacy,node_services toneAmber
class node_sync_engine,node_sqlite,node_indexeddb,node_crypto,node_key_storage,node_import_core,node_import_sp,node_query_client toneMint
class node_pg,node_queue,node_jobs,node_blob_api,node_storage,node_realtime,node_valkey,node_s3 toneRose
```

## Components

### API access

- [API server](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [REST routes](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/v1.ts): `apps/api/src/routes/v1.ts`
- [tRPC routes](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/trpc.ts): `apps/api/src/routes/trpc.ts`

### Plurality domains

- [Authentication](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/auth/index.ts): `apps/api/src/routes/auth/index.ts`
- [Accounts and friends](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/account/index.ts): `apps/api/src/routes/account/index.ts`
- [System and identity](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/systems/index.ts): `apps/api/src/routes/systems/index.ts`
- [Fronting and analytics](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/fronting-sessions/index.ts): `apps/api/src/routes/fronting-sessions/index.ts`
- [Communication](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/messages/index.ts): `apps/api/src/routes/messages/index.ts`
- [Privacy and sharing](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/buckets/index.ts): `apps/api/src/routes/buckets/index.ts`
- [Domain services](https://github.com/theprismsystem/pluralscape-mono/tree/main/apps/api/src/services): `apps/api/src/services`

### Client data

- [Offline sync engine](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/sync/src/engine/sync-engine.ts): `packages/sync/src/engine/sync-engine.ts`
- [SQLite sync storage](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/sync/src/adapters/sqlite-storage-adapter.ts): `packages/sync/src/adapters/sqlite-storage-adapter.ts`
- [Web sync storage](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/mobile/src/platform/drivers/indexeddb-storage-adapter.ts): `apps/mobile/src/platform/drivers/indexeddb-storage-adapter.ts`
- [Blob encryption](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/crypto/src/blob-pipeline/upload-pipeline.ts): `packages/crypto/src/blob-pipeline/upload-pipeline.ts`
- [Web key storage](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/crypto/src/web-key-storage.ts): `packages/crypto/src/web-key-storage.ts`
- [Import orchestration](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/import-core/src/import-engine.ts): `packages/import-core/src/import-engine.ts`
- [Simply Plural import](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/import-sp/src/engine/import-engine.ts): `packages/import-sp/src/engine/import-engine.ts`
- [Client query cache](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/data/src/query-client.ts): `packages/data/src/query-client.ts`

### Platform operations

- [PostgreSQL](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/lib/db.ts): `apps/api/src/lib/db.ts`
- [Background jobs](https://github.com/theprismsystem/pluralscape-mono/blob/main/packages/queue/src/adapters/bullmq/bullmq-job-worker.ts): `packages/queue/src/adapters/bullmq/bullmq-job-worker.ts`
- [API job handlers](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/jobs/webhook-deliver.ts): `apps/api/src/jobs/webhook-deliver.ts`
- [Blob API](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/routes/blobs/index.ts): `apps/api/src/routes/blobs/index.ts`
- [Blob storage](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/lib/storage.ts): `apps/api/src/lib/storage.ts`
- [Realtime notifications](https://github.com/theprismsystem/pluralscape-mono/blob/main/apps/api/src/lib/sse-manager.ts): `apps/api/src/lib/sse-manager.ts`
- **Valkey**
- **S3-compatible storage**

### Other components

- **User or client**

## Connections

- User or client → API server: sends requests
- API server → REST routes: dispatches REST
- API server → tRPC routes: dispatches tRPC
- REST routes → Authentication: routes requests
- REST routes → Accounts and friends: routes requests
- REST routes → System and identity: routes requests
- REST routes → Fronting and analytics: routes requests
- REST routes → Communication: routes requests
- REST routes → Privacy and sharing: routes requests
- tRPC routes → Authentication: routes requests
- tRPC routes → Accounts and friends: routes requests
- tRPC routes → System and identity: routes requests
- tRPC routes → Fronting and analytics: routes requests
- tRPC routes → Communication: routes requests
- tRPC routes → Privacy and sharing: routes requests
- Authentication → Domain services: invokes services
- Accounts and friends → Domain services: invokes services
- System and identity → Domain services: invokes services
- Fronting and analytics → Domain services: invokes services
- Communication → Domain services: invokes services
- Privacy and sharing → Domain services: invokes services
- Domain services → PostgreSQL: reads and writes
- User or client → Offline sync engine: uses client
- Offline sync engine → SQLite sync storage: stores encrypted changes
- Offline sync engine → Web sync storage: stores encrypted changes
- User or client → Blob encryption: prepares uploads
- Blob encryption → Web key storage: uses keys
- User or client → Import orchestration: starts import
- Simply Plural import → Import orchestration: shares orchestration
- Import orchestration → PostgreSQL: persists mapped data
- API job handlers → Background jobs: uses job queue
- Blob API → Blob storage: requests blob operations
- Blob storage → S3-compatible storage: stores blobs
- Realtime notifications → Valkey: uses pub-sub
- User or client → Client query cache: uses client data