# knaw-huc/annorepo architecture

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

- Interactive diagram: https://gitdiagram.com/knaw-huc/annorepo
- Repository: https://github.com/knaw-huc/annorepo

## Overview

AnnoRepo is a W3C Web Annotation Protocol service with custom batch-upload, search, and indexing APIs. A typical client sends annotation or query requests through the HTTP client to server resources; those resources use container persistence and, for search or index operations, background chore managers. Shared API types represent annotation pages and index types. The tree and excerpts also identify authentication, custom queries, and gRPC services. Some relationships and subsystem internals are documented or indexed but not sampled, so those links are dashed where their wiring is unverified.

Main entry points: [`server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt) (Container services), [`client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt`](https://github.com/knaw-huc/annorepo/blob/main/client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt) (AnnoRepo client), [`server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerDAO.kt`](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerDAO.kt) (Container storage), [`server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt`](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt) (Search manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and API"]
  node_clientlib["AnnoRepo client<br/>[AnnoRepoClient.kt]"]
  node_annotationpage["Annotation pages<br/>[AnnotationPage.kt]"]
  node_paths["API paths<br/>[ResourcePaths.kt]"]
  node_indextype["Index types<br/>[IndexType.kt]"]
end

subgraph group_http["HTTP resources"]
  node_containerresource["Container services"]
  node_globalresource["Global services"]
  node_w3cresource["W3C protocol<br/>[W3CResource.kt]"]
  node_batchresource["Batch upload<br/>[BatchResource.kt]"]
end

subgraph group_query["Search and indexing"]
  node_searchmanager["Search manager<br/>[SearchManager.kt]"]
  node_searchchore["Search jobs<br/>[SearchChore.kt]"]
  node_aggregatestages["Query stages"]
  node_indexmanager["Index manager<br/>[IndexManager.kt]"]
  node_indexchore["Index jobs<br/>[IndexChore.kt]"]
end

subgraph group_data["Persistence and identity"]
  node_containerdao[("Container storage<br/>[ContainerDAO.kt]")]
  node_customquerydao[("Custom queries<br/>[CustomQueryDAO.kt]")]
  node_containeruserdao[("Container access")]
  node_auth["Authentication"]
end

subgraph group_integration["Protocols and auth"]
  node_grpcupload["gRPC upload"]
  node_grpcsearch["gRPC search"]
end

node_user(("API user"))
node_openid(("OpenID provider"))
node_sram(("SRAM provider"))

node_user -.->|"uses"| node_clientlib
node_clientlib -->|"calls HTTP"| node_containerresource
node_clientlib -.->|"parses pages"| node_annotationpage
node_containerresource -->|"reads and writes"| node_containerdao
node_containerresource -->|"manages access"| node_containeruserdao
node_containerresource -->|"loads queries"| node_customquerydao
node_containerresource -->|"builds stages"| node_aggregatestages
node_containerresource -->|"starts indexing"| node_indexmanager
node_indexmanager -->|"gets collection"| node_containerdao
node_indexmanager -->|"dispatches job"| node_indexchore
node_globalresource -->|"starts searches"| node_searchmanager
node_searchmanager -->|"dispatches job"| node_searchchore
node_searchmanager -->|"supplies storage"| node_containerdao
node_containerresource -.->|"serves protocol"| node_w3cresource
node_clientlib -.->|"uploads batches"| node_batchresource
node_clientlib -.->|"requests search"| node_globalresource
node_containerresource -.->|"accepts index types"| node_indextype
node_grpcupload -->|"stores annotations"| node_containerdao
node_auth -.->|"authenticates with"| node_openid
node_auth -.->|"authenticates with"| node_sram

click node_clientlib "https://github.com/knaw-huc/annorepo/blob/main/client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt"
click node_annotationpage "https://github.com/knaw-huc/annorepo/blob/main/common/src/main/kotlin/nl/knaw/huc/annorepo/api/AnnotationPage.kt"
click node_paths "https://github.com/knaw-huc/annorepo/blob/main/common/src/main/kotlin/nl/knaw/huc/annorepo/api/ResourcePaths.kt"
click node_indextype "https://github.com/knaw-huc/annorepo/blob/main/common/src/main/kotlin/nl/knaw/huc/annorepo/api/IndexType.kt"
click node_containerresource "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt"
click node_globalresource "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/GlobalServiceResource.kt"
click node_w3cresource "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/W3CResource.kt"
click node_batchresource "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/BatchResource.kt"
click node_searchmanager "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt"
click node_searchchore "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchChore.kt"
click node_aggregatestages "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/AggregateStageGenerator.kt"
click node_indexmanager "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexManager.kt"
click node_indexchore "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexChore.kt"
click node_containerdao "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerDAO.kt"
click node_customquerydao "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/CustomQueryDAO.kt"
click node_containeruserdao "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerUserDAO.kt"
click node_auth "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/auth/AROAuthAuthenticator.kt"
click node_grpcupload "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationUploadService.kt"
click node_grpcsearch "https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationSearchService.kt"

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_clientlib,node_annotationpage,node_paths,node_indextype,node_user toneBlue
class node_containerresource,node_globalresource,node_w3cresource,node_batchresource toneAmber
class node_searchmanager,node_searchchore,node_aggregatestages,node_indexmanager,node_indexchore toneMint
class node_containerdao,node_customquerydao,node_containeruserdao,node_auth toneRose
class node_grpcupload,node_grpcsearch,node_openid,node_sram toneIndigo
```

## Components

### Client and API

- [AnnoRepo client](https://github.com/knaw-huc/annorepo/blob/main/client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt): `client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt`
- [Annotation pages](https://github.com/knaw-huc/annorepo/blob/main/common/src/main/kotlin/nl/knaw/huc/annorepo/api/AnnotationPage.kt): `common/src/main/kotlin/nl/knaw/huc/annorepo/api/AnnotationPage.kt`
- [API paths](https://github.com/knaw-huc/annorepo/blob/main/common/src/main/kotlin/nl/knaw/huc/annorepo/api/ResourcePaths.kt): `common/src/main/kotlin/nl/knaw/huc/annorepo/api/ResourcePaths.kt`
- [Index types](https://github.com/knaw-huc/annorepo/blob/main/common/src/main/kotlin/nl/knaw/huc/annorepo/api/IndexType.kt): `common/src/main/kotlin/nl/knaw/huc/annorepo/api/IndexType.kt`

### HTTP resources

- [Container services](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`
- [Global services](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/GlobalServiceResource.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/GlobalServiceResource.kt`
- [W3C protocol](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/W3CResource.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/W3CResource.kt`
- [Batch upload](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/BatchResource.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/BatchResource.kt`

### Search and indexing

- [Search manager](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt`
- [Search jobs](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchChore.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchChore.kt`
- [Query stages](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/AggregateStageGenerator.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/AggregateStageGenerator.kt`
- [Index manager](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexManager.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexManager.kt`
- [Index jobs](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexChore.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexChore.kt`

### Persistence and identity

- [Container storage](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerDAO.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerDAO.kt`
- [Custom queries](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/CustomQueryDAO.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/dao/CustomQueryDAO.kt`
- [Container access](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerUserDAO.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/dao/ContainerUserDAO.kt`
- [Authentication](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/auth/AROAuthAuthenticator.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/auth/AROAuthAuthenticator.kt`

### Protocols and auth

- [gRPC upload](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationUploadService.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationUploadService.kt`
- [gRPC search](https://github.com/knaw-huc/annorepo/blob/main/server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationSearchService.kt): `server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationSearchService.kt`

### Other components

- **API user**
- **OpenID provider**
- **SRAM provider**

## Connections

- API user → AnnoRepo client: uses
- AnnoRepo client → Container services: calls HTTP (evidence: `client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt`)
- AnnoRepo client → Annotation pages: parses pages (evidence: `client/src/main/kotlin/nl/knaw/huc/annorepo/client/AnnoRepoClient.kt`)
- Container services → Container storage: reads and writes (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`)
- Container services → Container access: manages access (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`)
- Container services → Custom queries: loads queries (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`)
- Container services → Query stages: builds stages (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`)
- Container services → Index manager: starts indexing (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`)
- Index manager → Container storage: gets collection (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexManager.kt`)
- Index manager → Index jobs: dispatches job (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/IndexManager.kt`)
- Global services → Search manager: starts searches (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/GlobalServiceResource.kt`)
- Search manager → Search jobs: dispatches job (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt`)
- Search manager → Container storage: supplies storage (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/tools/SearchManager.kt`)
- Container services → W3C protocol: serves protocol
- AnnoRepo client → Batch upload: uploads batches
- AnnoRepo client → Global services: requests search
- Container services → Index types: accepts index types (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/resources/ContainerServiceResource.kt`)
- gRPC upload → Container storage: stores annotations (evidence: `server/src/main/kotlin/nl/knaw/huc/annorepo/grpc/AnnotationUploadService.kt`)
- Authentication → OpenID provider: authenticates with
- Authentication → SRAM provider: authenticates with
