# biodiversitydata-se/sos architecture

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

## Overview

SOS is a species-observation aggregation and access platform: observations are harvested and validated, then exposed through search, adaptive location search, and analytical APIs. Users can also export results, while administrators manage providers, harvest jobs, caches, and system status. The graph includes stewardship and status-facing capabilities documented by the repository structure; several implementation paths were not sampled, so uncertain connections are omitted.

Main entry points: [`Src/SOS.Observations.Api/Controllers/ObservationsController.cs`](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Controllers/ObservationsController.cs) (Observation API), [`Src/SOS.Observations.Api/Services/AdaptiveSearchLocations/AdaptiveSearchLocationsService.cs`](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Services/AdaptiveSearchLocations/AdaptiveSearchLocationsService.cs) (Adaptive locations), [`Src/SOS.Status.Web.Client/HttpClients/ObservationsSearchApiClient.cs`](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Status.Web.Client/HttpClients/ObservationsSearchApiClient.cs) (Observations client), [`Src/SOS.Administration.Api/Controllers/HarvestAndProcessJobController.cs`](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Controllers/HarvestAndProcessJobController.cs) (Administration API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Search and access"]
  node_observations_api["Observation API"]
  node_adaptive_search["Adaptive locations"]
  node_search_store[("Processed observations")]
  node_status_web["Status web search"]
  node_search_client["Observations client"]
end

subgraph group_operations["Harvest operations"]
  node_admin["Administration API"]
  node_provider_admin["Provider management"]
  node_harvest_validation["Archive validation"]
  node_ipt_manager["IPT resource lookup<br/>[IptManager.cs]"]
end

subgraph group_analysis["Analysis"]
  node_analysis_api["Analysis API"]
  node_analysis_manager["Analysis manager<br/>[AnalysisManager.cs]"]
end

subgraph group_exports["Exports and storage"]
  node_export_jobs["Export jobs"]
  node_observation_export["Observation export"]
  node_blob_manager["Export file access"]
  node_blob_storage[("Blob storage")]
end

subgraph group_stewardship["Data stewardship"]
  node_stewardship_api["Stewardship API"]
  node_stewardship_manager["Stewardship manager"]
end

node_user(("API consumer"))
node_ipt(("GBIF IPT"))

node_user -->|"searches"| node_observations_api
node_observations_api -->|"builds location results"| node_adaptive_search
node_adaptive_search -->|"queries observations"| node_search_store
node_status_web -->|"calls"| node_search_client
node_search_client -->|"sends search"| node_observations_api
node_user -->|"manages harvest"| node_admin
node_admin -->|"requests validation"| node_harvest_validation
node_provider_admin -->|"lists IPT resources"| node_ipt_manager
node_ipt_manager -->|"fetches resource page"| node_ipt
node_user -->|"requests analysis"| node_analysis_api
node_analysis_api -->|"runs analysis"| node_analysis_manager
node_analysis_manager -->|"queries metrics"| node_search_store
node_user -->|"requests export"| node_export_jobs
node_export_jobs -->|"dispatches export"| node_observation_export
node_observation_export -->|"uploads files"| node_blob_storage
node_observations_api -->|"requests export files"| node_blob_manager
node_blob_manager -->|"lists and links files"| node_blob_storage
node_user -->|"searches records"| node_stewardship_api
node_stewardship_api -->|"delegates"| node_stewardship_manager

click node_observations_api "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Controllers/ObservationsController.cs"
click node_adaptive_search "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Services/AdaptiveSearchLocations/AdaptiveSearchLocationsService.cs"
click node_search_store "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Analysis.Api/Repositories/ProcessedObservationRepository.cs"
click node_status_web "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Status.Web/Services/ObservationSearchService.cs"
click node_search_client "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Status.Web.Client/HttpClients/ObservationsSearchApiClient.cs"
click node_admin "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Controllers/HarvestAndProcessJobController.cs"
click node_provider_admin "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Controllers/DataProvidersController.cs"
click node_harvest_validation "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Harvest/Managers/DwcaDataValidationReportManager.cs"
click node_ipt_manager "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Managers/IptManager.cs"
click node_analysis_api "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Analysis.Api/Controllers/AnalysisController.cs"
click node_analysis_manager "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Lib/Managers/AnalysisManager.cs"
click node_export_jobs "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Export/Jobs/ExportAndStoreJob.cs"
click node_observation_export "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Export/Managers/ObservationManager.cs"
click node_blob_manager "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Managers/BlobStorageManager.cs"
click node_blob_storage "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Lib/Services/BlobStorageService.cs"
click node_stewardship_api "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.DataStewardship.Api/Endpoints/Occurrences/GetOccurrencesBySearchEndpoint.cs"
click node_stewardship_manager "https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.DataStewardship.Api/Application/Managers/DataStewardshipManager.cs"

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_observations_api,node_adaptive_search,node_search_store,node_status_web,node_search_client toneBlue
class node_admin,node_provider_admin,node_harvest_validation,node_ipt_manager toneAmber
class node_analysis_api,node_analysis_manager,node_user toneMint
class node_export_jobs,node_observation_export,node_blob_manager,node_blob_storage toneRose
class node_stewardship_api,node_stewardship_manager,node_ipt toneIndigo
```

## Components

### Search and access

- [Observation API](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Controllers/ObservationsController.cs): `Src/SOS.Observations.Api/Controllers/ObservationsController.cs`
- [Adaptive locations](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Services/AdaptiveSearchLocations/AdaptiveSearchLocationsService.cs): `Src/SOS.Observations.Api/Services/AdaptiveSearchLocations/AdaptiveSearchLocationsService.cs`
- [Processed observations](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Analysis.Api/Repositories/ProcessedObservationRepository.cs): `Src/SOS.Analysis.Api/Repositories/ProcessedObservationRepository.cs`
- [Status web search](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Status.Web/Services/ObservationSearchService.cs): `Src/SOS.Status.Web/Services/ObservationSearchService.cs`
- [Observations client](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Status.Web.Client/HttpClients/ObservationsSearchApiClient.cs): `Src/SOS.Status.Web.Client/HttpClients/ObservationsSearchApiClient.cs`

### Harvest operations

- [Administration API](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Controllers/HarvestAndProcessJobController.cs): `Src/SOS.Administration.Api/Controllers/HarvestAndProcessJobController.cs`
- [Provider management](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Controllers/DataProvidersController.cs): `Src/SOS.Administration.Api/Controllers/DataProvidersController.cs`
- [Archive validation](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Harvest/Managers/DwcaDataValidationReportManager.cs): `Src/SOS.Harvest/Managers/DwcaDataValidationReportManager.cs`
- [IPT resource lookup](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Administration.Api/Managers/IptManager.cs): `Src/SOS.Administration.Api/Managers/IptManager.cs`

### Analysis

- [Analysis API](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Analysis.Api/Controllers/AnalysisController.cs): `Src/SOS.Analysis.Api/Controllers/AnalysisController.cs`
- [Analysis manager](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Lib/Managers/AnalysisManager.cs): `Src/SOS.Lib/Managers/AnalysisManager.cs`

### Exports and storage

- [Export jobs](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Export/Jobs/ExportAndStoreJob.cs): `Src/SOS.Export/Jobs/ExportAndStoreJob.cs`
- [Observation export](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Export/Managers/ObservationManager.cs): `Src/SOS.Export/Managers/ObservationManager.cs`
- [Export file access](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Observations.Api/Managers/BlobStorageManager.cs): `Src/SOS.Observations.Api/Managers/BlobStorageManager.cs`
- [Blob storage](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.Lib/Services/BlobStorageService.cs): `Src/SOS.Lib/Services/BlobStorageService.cs`

### Data stewardship

- [Stewardship API](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.DataStewardship.Api/Endpoints/Occurrences/GetOccurrencesBySearchEndpoint.cs): `Src/SOS.DataStewardship.Api/Endpoints/Occurrences/GetOccurrencesBySearchEndpoint.cs`
- [Stewardship manager](https://github.com/biodiversitydata-se/sos/blob/master/Src/SOS.DataStewardship.Api/Application/Managers/DataStewardshipManager.cs): `Src/SOS.DataStewardship.Api/Application/Managers/DataStewardshipManager.cs`

### Other components

- **API consumer**
- **GBIF IPT**

## Connections

- API consumer → Observation API: searches
- Observation API → Adaptive locations: builds location results
- Adaptive locations → Processed observations: queries observations
- Status web search → Observations client: calls
- Observations client → Observation API: sends search
- API consumer → Administration API: manages harvest
- Administration API → Archive validation: requests validation
- Provider management → IPT resource lookup: lists IPT resources
- IPT resource lookup → GBIF IPT: fetches resource page
- API consumer → Analysis API: requests analysis
- Analysis API → Analysis manager: runs analysis
- Analysis manager → Processed observations: queries metrics
- API consumer → Export jobs: requests export
- Export jobs → Observation export: dispatches export
- Observation export → Blob storage: uploads files
- Observation API → Export file access: requests export files
- Export file access → Blob storage: lists and links files
- API consumer → Stewardship API: searches records
- Stewardship API → Stewardship manager: delegates