# chive-pub/chive architecture

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

- Interactive diagram: https://gitdiagram.com/chive-pub/chive
- Repository: https://github.com/chive-pub/chive

## Overview

Chive is a decentralized scholarly eprint AppView: researchers publish records to their own PDS, and Chive indexes ATProto firehose events to provide search, review, graph, and discovery features. The README documents this principal workflow and product capabilities; the tree supports the major API, service, storage, and web subsystems, but most runtime wiring was not sampled. Arrows therefore show only documented firehose flow and sampled direct calls or storage access, not presumed links among unsampled handlers and services.

Main entry points: [`src/api/server.ts`](https://github.com/chive-pub/chive/blob/main/src/api/server.ts) (XRPC and REST API), [`src/services/indexing/firehose-consumer.ts`](https://github.com/chive-pub/chive/blob/main/src/services/indexing/firehose-consumer.ts) (Firehose consumer), [`src/services/indexing/event-processor.ts`](https://github.com/chive-pub/chive/blob/main/src/services/indexing/event-processor.ts) (Event processor), [`src/services/review/review-service.ts`](https://github.com/chive-pub/chive/blob/main/src/services/review/review-service.ts) (Review service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["User experience"]
  node_web["Web application<br/>[page.tsx]"]
  node_api["XRPC and REST API<br/>[server.ts]"]
end

subgraph group_ingest["ATProto indexing"]
  node_indexer["Indexer entry<br/>[indexer.ts]"]
  node_consumer["Firehose consumer"]
  node_processor["Event processor<br/>[event-processor.ts]"]
end

subgraph group_domain["Scholarly services"]
  node_eprint["Eprint service<br/>[eprint-service.ts]"]
  node_review["Review service<br/>[review-service.ts]"]
  node_search["Search service<br/>[search-service.ts]"]
  node_knowledge["Knowledge graph<br/>[graph-service.ts]"]
  node_discovery["Discovery service"]
  node_plugins["Plugin manager<br/>[plugin-manager.ts]"]
end

subgraph group_persistence["Indexed storage"]
  node_postgres[("PostgreSQL index<br/>[adapter.ts]")]
  node_elastic[("Elasticsearch<br/>[adapter.ts]")]
  node_neo4j[("Neo4j graph<br/>[adapter.ts]")]
  node_redis[("Redis<br/>[structures.ts]")]
  node_reviewrepo["Review repository"]
  node_tagmanager["Tag manager<br/>[tag-manager.ts]"]
end

subgraph group_security["Identity and plugins"]
  node_auth["Authorization"]
end

node_researcher(("Researcher"))
node_pds[("User PDS")]
node_relay(("ATProto relay"))

node_researcher -->|"publishes records"| node_pds
node_pds -->|"streams events"| node_relay
node_relay -->|"firehose events"| node_consumer
node_indexer -->|"starts"| node_consumer
node_consumer -->|"dispatches events"| node_processor
node_processor -->|"indexes eprints"| node_eprint
node_processor -->|"indexes reviews"| node_review
node_review -->|"queries reviews"| node_reviewrepo
node_reviewrepo -->|"reads and writes"| node_postgres
node_tagmanager -->|"queries graph"| node_neo4j
node_auth -->|"stores roles"| node_redis
node_web -->|"API requests"| node_api
node_api -->|"authorizes requests"| node_auth
node_api -->|"serves eprint operations"| node_eprint
node_api -->|"serves review operations"| node_review
node_api -->|"serves search"| node_search
node_api -->|"serves graph operations"| node_knowledge
node_api -->|"serves discovery"| node_discovery
node_search -->|"searches index"| node_elastic
node_knowledge -->|"queries graph"| node_neo4j
node_discovery -->|"uses graph data"| node_neo4j
node_researcher -->|"browses and searches"| node_web
node_plugins -.->|"optional event hooks"| node_consumer

click node_web "https://github.com/chive-pub/chive/blob/main/web/app/(search)/search/page.tsx"
click node_api "https://github.com/chive-pub/chive/blob/main/src/api/server.ts"
click node_indexer "https://github.com/chive-pub/chive/blob/main/src/indexer.ts"
click node_consumer "https://github.com/chive-pub/chive/blob/main/src/services/indexing/firehose-consumer.ts"
click node_processor "https://github.com/chive-pub/chive/blob/main/src/services/indexing/event-processor.ts"
click node_eprint "https://github.com/chive-pub/chive/blob/main/src/services/eprint/eprint-service.ts"
click node_review "https://github.com/chive-pub/chive/blob/main/src/services/review/review-service.ts"
click node_search "https://github.com/chive-pub/chive/blob/main/src/services/search/search-service.ts"
click node_knowledge "https://github.com/chive-pub/chive/blob/main/src/services/knowledge-graph/graph-service.ts"
click node_discovery "https://github.com/chive-pub/chive/blob/main/src/services/discovery/discovery-service.ts"
click node_plugins "https://github.com/chive-pub/chive/blob/main/src/plugins/core/plugin-manager.ts"
click node_auth "https://github.com/chive-pub/chive/blob/main/src/auth/authorization/authorization-service.ts"
click node_postgres "https://github.com/chive-pub/chive/blob/main/src/storage/postgresql/adapter.ts"
click node_elastic "https://github.com/chive-pub/chive/blob/main/src/storage/elasticsearch/adapter.ts"
click node_neo4j "https://github.com/chive-pub/chive/blob/main/src/storage/neo4j/adapter.ts"
click node_redis "https://github.com/chive-pub/chive/blob/main/src/storage/redis/structures.ts"
click node_reviewrepo "https://github.com/chive-pub/chive/blob/main/src/storage/postgresql/reviews-repository.ts"
click node_tagmanager "https://github.com/chive-pub/chive/blob/main/src/storage/neo4j/tag-manager.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_web,node_api toneBlue
class node_indexer,node_consumer,node_processor,node_pds toneAmber
class node_eprint,node_review,node_search,node_knowledge,node_discovery,node_plugins toneMint
class node_postgres,node_elastic,node_neo4j,node_redis,node_reviewrepo,node_tagmanager toneRose
class node_auth,node_researcher,node_relay toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/chive-pub/chive/blob/main/web/app/(search)/search/page.tsx): `web/app/(search)/search/page.tsx`
- [XRPC and REST API](https://github.com/chive-pub/chive/blob/main/src/api/server.ts): `src/api/server.ts`

### ATProto indexing

- [Indexer entry](https://github.com/chive-pub/chive/blob/main/src/indexer.ts): `src/indexer.ts`
- [Firehose consumer](https://github.com/chive-pub/chive/blob/main/src/services/indexing/firehose-consumer.ts): `src/services/indexing/firehose-consumer.ts`
- [Event processor](https://github.com/chive-pub/chive/blob/main/src/services/indexing/event-processor.ts): `src/services/indexing/event-processor.ts`

### Scholarly services

- [Eprint service](https://github.com/chive-pub/chive/blob/main/src/services/eprint/eprint-service.ts): `src/services/eprint/eprint-service.ts`
- [Review service](https://github.com/chive-pub/chive/blob/main/src/services/review/review-service.ts): `src/services/review/review-service.ts`
- [Search service](https://github.com/chive-pub/chive/blob/main/src/services/search/search-service.ts): `src/services/search/search-service.ts`
- [Knowledge graph](https://github.com/chive-pub/chive/blob/main/src/services/knowledge-graph/graph-service.ts): `src/services/knowledge-graph/graph-service.ts`
- [Discovery service](https://github.com/chive-pub/chive/blob/main/src/services/discovery/discovery-service.ts): `src/services/discovery/discovery-service.ts`
- [Plugin manager](https://github.com/chive-pub/chive/blob/main/src/plugins/core/plugin-manager.ts): `src/plugins/core/plugin-manager.ts`

### Indexed storage

- [PostgreSQL index](https://github.com/chive-pub/chive/blob/main/src/storage/postgresql/adapter.ts): `src/storage/postgresql/adapter.ts`
- [Elasticsearch](https://github.com/chive-pub/chive/blob/main/src/storage/elasticsearch/adapter.ts): `src/storage/elasticsearch/adapter.ts`
- [Neo4j graph](https://github.com/chive-pub/chive/blob/main/src/storage/neo4j/adapter.ts): `src/storage/neo4j/adapter.ts`
- [Redis](https://github.com/chive-pub/chive/blob/main/src/storage/redis/structures.ts): `src/storage/redis/structures.ts`
- [Review repository](https://github.com/chive-pub/chive/blob/main/src/storage/postgresql/reviews-repository.ts): `src/storage/postgresql/reviews-repository.ts`
- [Tag manager](https://github.com/chive-pub/chive/blob/main/src/storage/neo4j/tag-manager.ts): `src/storage/neo4j/tag-manager.ts`

### Identity and plugins

- [Authorization](https://github.com/chive-pub/chive/blob/main/src/auth/authorization/authorization-service.ts): `src/auth/authorization/authorization-service.ts`

### Other components

- **Researcher**
- **User PDS**
- **ATProto relay**

## Connections

- Researcher → User PDS: publishes records
- User PDS → ATProto relay: streams events
- ATProto relay → Firehose consumer: firehose events
- Indexer entry → Firehose consumer: starts
- Firehose consumer → Event processor: dispatches events
- Event processor → Eprint service: indexes eprints
- Event processor → Review service: indexes reviews
- Review service → Review repository: queries reviews
- Review repository → PostgreSQL index: reads and writes
- Tag manager → Neo4j graph: queries graph
- Authorization → Redis: stores roles
- Web application → XRPC and REST API: API requests
- XRPC and REST API → Authorization: authorizes requests
- XRPC and REST API → Eprint service: serves eprint operations
- XRPC and REST API → Review service: serves review operations
- XRPC and REST API → Search service: serves search
- XRPC and REST API → Knowledge graph: serves graph operations
- XRPC and REST API → Discovery service: serves discovery
- Search service → Elasticsearch: searches index
- Knowledge graph → Neo4j graph: queries graph
- Discovery service → Neo4j graph: uses graph data
- Researcher → Web application: browses and searches
- Plugin manager → Firehose consumer: optional event hooks