# sunet/eduseal architecture

> Architecture diagram of the GitHub repository sunet/eduseal, 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/sunet/eduseal
- Repository: https://github.com/sunet/eduseal

## Overview

eduSeal is a PDF-sealing and signature-validation service: clients submit PDFs through the API gateway, sealing is dispatched asynchronously, and completed documents can be retrieved or validated. Separate Python services perform PKCS#11-backed signing and gRPC validation; the gateway also uses persistent storage and NATS. The excerpts show gateway construction and the sealer’s queue handling, but do not expose all HTTP routing, cache-stream persistence, or validation-call details, so those connections are omitted where they cannot be evidenced.

Main entry points: [`cmd/apigw/main.go`](https://github.com/sunet/eduseal/blob/main/cmd/apigw/main.go) (Gateway Startup), [`src/eduseal/sealer/run.py`](https://github.com/sunet/eduseal/blob/main/src/eduseal/sealer/run.py) (Sealer Worker), [`src/eduseal/validator/run.py`](https://github.com/sunet/eduseal/blob/main/src/eduseal/validator/run.py) (Validator Worker), [`internal/apigw/apiv1/handlers_eduseal.go`](https://github.com/sunet/eduseal/blob/main/internal/apigw/apiv1/handlers_eduseal.go) (PDF API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API Gateway"]
  node_entry["Gateway Startup<br/>[main.go]"]
  node_http["HTTP Server"]
  node_handlers["PDF API"]
  node_grpcapi["API gRPC Client<br/>[client.go]"]
end

subgraph group_async["Async Sealing"]
  node_stream["Stream Service<br/>[service.go]"]
  node_sealstream["Seal Stream<br/>[seal_stream.go]"]
  node_cachestream["Cache Stream<br/>[cache_stream.go]"]
  node_sealer["Sealer Worker<br/>[run.py]"]
  node_sealconfig["Sealer Config<br/>[config.py]"]
end

subgraph group_validation["Signature Validation"]
  node_validator["Validator Worker<br/>[run.py]"]
  node_validatorconfig["Validator Config<br/>[config.py]"]
end

subgraph group_platform["Shared Infrastructure"]
  node_kv["KV Client<br/>[client.go]"]
  node_certreload["Python Cert Reloader<br/>[cert_reloader.py]"]
  node_govalidator["Validator gRPC Client<br/>[validator.go]"]
  node_observability["Telemetry<br/>[otel.go]"]
end

node_client(("API Client"))
node_nats["NATS"]
node_pkcs11["PKCS&#35;11 Signer"]
node_trustroots["Trust Certificates"]

node_entry -->|"creates"| node_http
node_entry -->|"creates"| node_handlers
node_entry -->|"creates"| node_stream
node_entry -->|"creates"| node_grpcapi
node_entry -->|"creates"| node_kv
node_client -.->|"sends requests"| node_http
node_http -.->|"dispatches"| node_handlers
node_handlers -->|"publishes seal"| node_stream
node_handlers -->|"reads signed PDF"| node_kv
node_stream -->|"connects"| node_nats
node_sealer -->|"loads config"| node_sealconfig
node_sealer -->|"consumes seal jobs"| node_nats
node_sealer -->|"publishes sealed result"| node_nats
node_sealer -->|"signs PDF"| node_pkcs11
node_sealer -->|"uses"| node_certreload
node_validator -->|"loads config"| node_validatorconfig
node_validator -->|"loads trust roots"| node_trustroots
node_validator -->|"uses"| node_certreload
node_govalidator -.->|"calls gRPC"| node_validator
node_entry -->|"initializes"| node_observability

click node_entry "https://github.com/sunet/eduseal/blob/main/cmd/apigw/main.go"
click node_http "https://github.com/sunet/eduseal/tree/main/internal/apigw/httpserver"
click node_handlers "https://github.com/sunet/eduseal/blob/main/internal/apigw/apiv1/handlers_eduseal.go"
click node_grpcapi "https://github.com/sunet/eduseal/blob/main/pkg/grpcclient/client.go"
click node_stream "https://github.com/sunet/eduseal/blob/main/internal/apigw/stream/service.go"
click node_sealstream "https://github.com/sunet/eduseal/blob/main/internal/apigw/stream/seal_stream.go"
click node_cachestream "https://github.com/sunet/eduseal/blob/main/internal/apigw/stream/cache_stream.go"
click node_sealer "https://github.com/sunet/eduseal/blob/main/src/eduseal/sealer/run.py"
click node_sealconfig "https://github.com/sunet/eduseal/blob/main/src/eduseal/sealer/config.py"
click node_kv "https://github.com/sunet/eduseal/blob/main/pkg/kvclient/client.go"
click node_validator "https://github.com/sunet/eduseal/blob/main/src/eduseal/validator/run.py"
click node_validatorconfig "https://github.com/sunet/eduseal/blob/main/src/eduseal/validator/config.py"
click node_certreload "https://github.com/sunet/eduseal/blob/main/src/eduseal/cert_reloader.py"
click node_govalidator "https://github.com/sunet/eduseal/blob/main/pkg/grpcclient/validator.go"
click node_observability "https://github.com/sunet/eduseal/blob/main/pkg/trace/otel.go"

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_entry,node_http,node_handlers,node_grpcapi,node_client toneBlue
class node_stream,node_sealstream,node_cachestream,node_sealer,node_sealconfig toneAmber
class node_validator,node_validatorconfig toneMint
class node_kv,node_certreload,node_govalidator,node_observability toneRose
class node_nats,node_pkcs11,node_trustroots toneIndigo
```

## Components

### API Gateway

- [Gateway Startup](https://github.com/sunet/eduseal/blob/main/cmd/apigw/main.go): `cmd/apigw/main.go`
- [HTTP Server](https://github.com/sunet/eduseal/tree/main/internal/apigw/httpserver): `internal/apigw/httpserver`
- [PDF API](https://github.com/sunet/eduseal/blob/main/internal/apigw/apiv1/handlers_eduseal.go): `internal/apigw/apiv1/handlers_eduseal.go`
- [API gRPC Client](https://github.com/sunet/eduseal/blob/main/pkg/grpcclient/client.go): `pkg/grpcclient/client.go`

### Async Sealing

- [Stream Service](https://github.com/sunet/eduseal/blob/main/internal/apigw/stream/service.go): `internal/apigw/stream/service.go`
- [Seal Stream](https://github.com/sunet/eduseal/blob/main/internal/apigw/stream/seal_stream.go): `internal/apigw/stream/seal_stream.go`
- [Cache Stream](https://github.com/sunet/eduseal/blob/main/internal/apigw/stream/cache_stream.go): `internal/apigw/stream/cache_stream.go`
- [Sealer Worker](https://github.com/sunet/eduseal/blob/main/src/eduseal/sealer/run.py): `src/eduseal/sealer/run.py`
- [Sealer Config](https://github.com/sunet/eduseal/blob/main/src/eduseal/sealer/config.py): `src/eduseal/sealer/config.py`

### Signature Validation

- [Validator Worker](https://github.com/sunet/eduseal/blob/main/src/eduseal/validator/run.py): `src/eduseal/validator/run.py`
- [Validator Config](https://github.com/sunet/eduseal/blob/main/src/eduseal/validator/config.py): `src/eduseal/validator/config.py`

### Shared Infrastructure

- [KV Client](https://github.com/sunet/eduseal/blob/main/pkg/kvclient/client.go): `pkg/kvclient/client.go`
- [Python Cert Reloader](https://github.com/sunet/eduseal/blob/main/src/eduseal/cert_reloader.py): `src/eduseal/cert_reloader.py`
- [Validator gRPC Client](https://github.com/sunet/eduseal/blob/main/pkg/grpcclient/validator.go): `pkg/grpcclient/validator.go`
- [Telemetry](https://github.com/sunet/eduseal/blob/main/pkg/trace/otel.go): `pkg/trace/otel.go`

### Other components

- **API Client**
- **NATS**
- **PKCS#11 Signer**
- **Trust Certificates**

## Connections

- Gateway Startup → HTTP Server: creates (evidence: `cmd/apigw/main.go`)
- Gateway Startup → PDF API: creates (evidence: `cmd/apigw/main.go`)
- Gateway Startup → Stream Service: creates (evidence: `cmd/apigw/main.go`)
- Gateway Startup → API gRPC Client: creates (evidence: `cmd/apigw/main.go`)
- Gateway Startup → KV Client: creates (evidence: `cmd/apigw/main.go`)
- API Client → HTTP Server: sends requests
- HTTP Server → PDF API: dispatches
- PDF API → Stream Service: publishes seal (evidence: `internal/apigw/apiv1/handlers_eduseal.go`)
- PDF API → KV Client: reads signed PDF (evidence: `internal/apigw/apiv1/handlers_eduseal.go`)
- Stream Service → NATS: connects (evidence: `internal/apigw/stream/service.go`)
- Sealer Worker → Sealer Config: loads config (evidence: `src/eduseal/sealer/run.py`)
- Sealer Worker → NATS: consumes seal jobs (evidence: `src/eduseal/sealer/run.py`)
- Sealer Worker → NATS: publishes sealed result (evidence: `src/eduseal/sealer/run.py`)
- Sealer Worker → PKCS#11 Signer: signs PDF (evidence: `src/eduseal/sealer/run.py`)
- Sealer Worker → Python Cert Reloader: uses (evidence: `src/eduseal/sealer/run.py`)
- Validator Worker → Validator Config: loads config (evidence: `src/eduseal/validator/run.py`)
- Validator Worker → Trust Certificates: loads trust roots (evidence: `src/eduseal/validator/run.py`)
- Validator Worker → Python Cert Reloader: uses (evidence: `src/eduseal/validator/run.py`)
- Validator gRPC Client → Validator Worker: calls gRPC
- Gateway Startup → Telemetry: initializes (evidence: `cmd/apigw/main.go`)
