# meigoc/tulpar-server architecture

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

- Interactive diagram: https://gitdiagram.com/meigoc/tulpar-server
- Repository: https://github.com/meigoc/tulpar-server

## Overview

Tulpar Server hosts a NurOS APG package repository. The main workflow is package browsing and download, alongside authenticated publish/yank: uploaded archives are validated, stored verbatim, and indexed for API access. Supporting layers cover APG parsing, repository state, request security, and operational controls. The README documents the product capabilities; edges based on implementation are limited to relationships visible in excerpts or SOURCE INDEX references, so some internal routing and configuration wiring is not expanded.

Main entry points: [`src/main/kotlin/meigo/tulpar/server/ServerContext.kt`](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/ServerContext.kt) (Shared context), [`src/main/kotlin/meigo/tulpar/server/repo/Repository.kt`](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/Repository.kt) (Repository index), [`src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt`](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt) (Publish and yank), [`src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt`](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt) (Publish service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_main["CLI entry<br/>[Main.kt]"]
  node_commands["Server commands<br/>[Commands.kt]"]
  node_config["Runtime config<br/>[TulparConfig.kt]"]
  node_context["Shared context<br/>[ServerContext.kt]"]
end

subgraph group_api["REST API"]
  node_webmodule["Web module<br/>[WebModule.kt]"]
  node_packageapi["Package browsing<br/>[PackageRoutes.kt]"]
  node_downloadapi["Package downloads<br/>[DownloadRoutes.kt]"]
  node_publishapi["Publish and yank<br/>[PublishRoutes.kt]"]
end

subgraph group_packages["APG and repository"]
  node_publish["Publish service<br/>[PublishService.kt]"]
  node_validator["APG validation<br/>[ApgValidator.kt]"]
  node_archive["Archive reader<br/>[ApgArchive.kt]"]
  node_checksums["Checksum parsing<br/>[Checksums.kt]"]
  node_metadata["APG metadata<br/>[Metadata.kt]"]
  node_version["Version handling<br/>[Version.kt]"]
  node_repository[("Repository index<br/>[Repository.kt]")]
  node_entries["Package records<br/>[PackageEntry.kt]"]
  node_repodata["Index document<br/>[RepoData.kt]"]
end

subgraph group_protection["Security controls"]
  node_ipguard["IP request guard<br/>[IpGuard.kt]"]
  node_limiter["Download limiter<br/>[DownloadLimiter.kt]"]
  node_tokenauth["Token auth<br/>[TokenAuth.kt]"]
  node_pathsafe["Path safety<br/>[PathSafety.kt]"]
end

subgraph group_operations["Operations"]
  node_metrics["Metrics collector"]
  node_console["Admin console<br/>[AdminConsole.kt]"]
  node_requestlog["Request log<br/>[RequestLog.kt]"]
end

node_client(("Package client"))
node_admin(("Administrator"))

node_admin -->|"starts server"| node_main
node_main -->|"dispatches commands"| node_commands
node_commands -->|"loads config"| node_config
node_commands -->|"builds context"| node_context
node_context -->|"holds config"| node_config
node_context -->|"holds repository"| node_repository
node_context -->|"holds limiter"| node_limiter
node_webmodule -->|"uses context"| node_context
node_client -->|"browses packages"| node_packageapi
node_client -->|"requests downloads"| node_downloadapi
node_client -->|"uploads or yanks"| node_publishapi
node_packageapi -->|"queries index"| node_repository
node_downloadapi -->|"resolves package"| node_repository
node_downloadapi -->|"limits streams"| node_limiter
node_publishapi -->|"invokes publish"| node_publish
node_publishapi -->|"checks bearer token"| node_tokenauth
node_publishapi -->|"checks path segments"| node_pathsafe
node_publish -->|"validates archive"| node_validator
node_publish -->|"reads archive"| node_archive
node_publish -->|"stores and reindexes"| node_repository
node_validator -->|"inspects contents"| node_archive
node_validator -->|"parses checksums"| node_checksums
node_repository -->|"scans packages"| node_archive
node_repository -->|"indexes entries"| node_entries
node_repository -->|"builds index"| node_repodata
node_console -->|"operates server"| node_context
node_console -->|"views metrics"| node_metrics
node_metrics -->|"samples runtime"| node_context
node_context -->|"holds guard"| node_ipguard
node_context -->|"holds authenticator"| node_tokenauth
node_context -->|"holds request log"| node_requestlog

click node_main "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/Main.kt"
click node_commands "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/cli/Commands.kt"
click node_config "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/config/TulparConfig.kt"
click node_context "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/ServerContext.kt"
click node_webmodule "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/WebModule.kt"
click node_packageapi "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/PackageRoutes.kt"
click node_downloadapi "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/DownloadRoutes.kt"
click node_publishapi "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt"
click node_publish "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt"
click node_validator "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/ApgValidator.kt"
click node_archive "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/ApgArchive.kt"
click node_checksums "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/Checksums.kt"
click node_metadata "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/Metadata.kt"
click node_version "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/Version.kt"
click node_repository "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/Repository.kt"
click node_entries "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/PackageEntry.kt"
click node_repodata "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/RepoData.kt"
click node_ipguard "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/IpGuard.kt"
click node_limiter "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/DownloadLimiter.kt"
click node_tokenauth "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/TokenAuth.kt"
click node_pathsafe "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/PathSafety.kt"
click node_metrics "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/metrics/MetricsCollector.kt"
click node_console "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/cli/AdminConsole.kt"
click node_requestlog "https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/util/RequestLog.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_main,node_commands,node_config,node_context,node_client toneBlue
class node_webmodule,node_packageapi,node_downloadapi,node_publishapi toneAmber
class node_publish,node_validator,node_archive,node_checksums,node_metadata,node_version,node_repository,node_entries,node_repodata toneMint
class node_ipguard,node_limiter,node_tokenauth,node_pathsafe toneRose
class node_metrics,node_console,node_requestlog,node_admin toneIndigo
```

## Components

### Server runtime

- [CLI entry](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/Main.kt): `src/main/kotlin/meigo/tulpar/server/Main.kt`
- [Server commands](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/cli/Commands.kt): `src/main/kotlin/meigo/tulpar/server/cli/Commands.kt`
- [Runtime config](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/config/TulparConfig.kt): `src/main/kotlin/meigo/tulpar/server/config/TulparConfig.kt`
- [Shared context](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/ServerContext.kt): `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`

### REST API

- [Web module](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/WebModule.kt): `src/main/kotlin/meigo/tulpar/server/web/WebModule.kt`
- [Package browsing](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/PackageRoutes.kt): `src/main/kotlin/meigo/tulpar/server/web/PackageRoutes.kt`
- [Package downloads](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/DownloadRoutes.kt): `src/main/kotlin/meigo/tulpar/server/web/DownloadRoutes.kt`
- [Publish and yank](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt): `src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt`

### APG and repository

- [Publish service](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt): `src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt`
- [APG validation](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/ApgValidator.kt): `src/main/kotlin/meigo/tulpar/server/apg/ApgValidator.kt`
- [Archive reader](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/ApgArchive.kt): `src/main/kotlin/meigo/tulpar/server/apg/ApgArchive.kt`
- [Checksum parsing](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/Checksums.kt): `src/main/kotlin/meigo/tulpar/server/apg/Checksums.kt`
- [APG metadata](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/Metadata.kt): `src/main/kotlin/meigo/tulpar/server/apg/Metadata.kt`
- [Version handling](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/apg/Version.kt): `src/main/kotlin/meigo/tulpar/server/apg/Version.kt`
- [Repository index](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/Repository.kt): `src/main/kotlin/meigo/tulpar/server/repo/Repository.kt`
- [Package records](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/PackageEntry.kt): `src/main/kotlin/meigo/tulpar/server/repo/PackageEntry.kt`
- [Index document](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/repo/RepoData.kt): `src/main/kotlin/meigo/tulpar/server/repo/RepoData.kt`

### Security controls

- [IP request guard](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/IpGuard.kt): `src/main/kotlin/meigo/tulpar/server/security/IpGuard.kt`
- [Download limiter](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/DownloadLimiter.kt): `src/main/kotlin/meigo/tulpar/server/security/DownloadLimiter.kt`
- [Token auth](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/TokenAuth.kt): `src/main/kotlin/meigo/tulpar/server/security/TokenAuth.kt`
- [Path safety](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/security/PathSafety.kt): `src/main/kotlin/meigo/tulpar/server/security/PathSafety.kt`

### Operations

- [Metrics collector](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/metrics/MetricsCollector.kt): `src/main/kotlin/meigo/tulpar/server/metrics/MetricsCollector.kt`
- [Admin console](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/cli/AdminConsole.kt): `src/main/kotlin/meigo/tulpar/server/cli/AdminConsole.kt`
- [Request log](https://github.com/meigoc/tulpar-server/blob/main/src/main/kotlin/meigo/tulpar/server/util/RequestLog.kt): `src/main/kotlin/meigo/tulpar/server/util/RequestLog.kt`

### Other components

- **Package client**
- **Administrator**

## Connections

- Administrator → CLI entry: starts server (evidence: `README.md`)
- CLI entry → Server commands: dispatches commands (evidence: `README.md`)
- Server commands → Runtime config: loads config (evidence: `src/main/kotlin/meigo/tulpar/server/cli/Commands.kt`)
- Server commands → Shared context: builds context (evidence: `src/main/kotlin/meigo/tulpar/server/cli/Commands.kt`)
- Shared context → Runtime config: holds config (evidence: `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`)
- Shared context → Repository index: holds repository (evidence: `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`)
- Shared context → Download limiter: holds limiter (evidence: `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`)
- Web module → Shared context: uses context (evidence: `src/main/kotlin/meigo/tulpar/server/web/WebModule.kt`)
- Package client → Package browsing: browses packages (evidence: `README.md`)
- Package client → Package downloads: requests downloads (evidence: `README.md`)
- Package client → Publish and yank: uploads or yanks (evidence: `README.md`)
- Package browsing → Repository index: queries index (evidence: `src/main/kotlin/meigo/tulpar/server/web/PackageRoutes.kt`)
- Package downloads → Repository index: resolves package (evidence: `src/main/kotlin/meigo/tulpar/server/web/DownloadRoutes.kt`)
- Package downloads → Download limiter: limits streams (evidence: `src/main/kotlin/meigo/tulpar/server/web/DownloadRoutes.kt`)
- Publish and yank → Publish service: invokes publish (evidence: `src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt`)
- Publish and yank → Token auth: checks bearer token (evidence: `src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt`)
- Publish and yank → Path safety: checks path segments (evidence: `src/main/kotlin/meigo/tulpar/server/web/PublishRoutes.kt`)
- Publish service → APG validation: validates archive (evidence: `src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt`)
- Publish service → Archive reader: reads archive (evidence: `src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt`)
- Publish service → Repository index: stores and reindexes (evidence: `src/main/kotlin/meigo/tulpar/server/repo/PublishService.kt`)
- APG validation → Archive reader: inspects contents (evidence: `src/main/kotlin/meigo/tulpar/server/apg/ApgValidator.kt`)
- APG validation → Checksum parsing: parses checksums (evidence: `src/main/kotlin/meigo/tulpar/server/apg/ApgValidator.kt`)
- Repository index → Archive reader: scans packages (evidence: `src/main/kotlin/meigo/tulpar/server/repo/Repository.kt`)
- Repository index → Package records: indexes entries (evidence: `src/main/kotlin/meigo/tulpar/server/repo/Repository.kt`)
- Repository index → Index document: builds index (evidence: `src/main/kotlin/meigo/tulpar/server/repo/Repository.kt`)
- Admin console → Shared context: operates server (evidence: `src/main/kotlin/meigo/tulpar/server/cli/AdminConsole.kt`)
- Admin console → Metrics collector: views metrics (evidence: `src/main/kotlin/meigo/tulpar/server/cli/AdminConsole.kt`)
- Metrics collector → Shared context: samples runtime (evidence: `src/main/kotlin/meigo/tulpar/server/metrics/MetricsCollector.kt`)
- Shared context → IP request guard: holds guard (evidence: `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`)
- Shared context → Token auth: holds authenticator (evidence: `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`)
- Shared context → Request log: holds request log (evidence: `src/main/kotlin/meigo/tulpar/server/ServerContext.kt`)
