# an-empty-string/amethyst architecture

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

- Interactive diagram: https://gitdiagram.com/an-empty-string/amethyst
- Repository: https://github.com/an-empty-string/amethyst

## Overview

Amethyst serves Gemini requests by selecting a configured host and resource, then returning a Gemini response. Its filesystem resource supports metadata-based directory handling, file delivery, and optional CGI; bundled extensions provide Python documentation browsing and redirects. The README documents entry-point extensibility, while the sampled excerpts do not show configuration loading or resource-registry internals, so those links are limited to the documented integration. Several core modules are represented by their exact tree paths without claims about unsampled implementation details.

Main entry points: [`amethyst/amethyst/resource.py`](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py) (Filesystem resource), [`amethyst/amethyst/server.py`](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/server.py) (Connection server), [`amethyst/amethyst/response.py`](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/response.py) (Gemini response), [`amethyst/amethyst/handler.py`](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/handler.py) (Generic handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Gemini server"]
  node_server_runtime["Connection server<br/>[server.py]"]
  node_tls["TLS and SNI<br/>[tls.py]"]
  node_config["Server configuration<br/>[config.py]"]
  node_manager["Server manager<br/>[kindergarten.py]"]
  node_handler["Generic handler<br/>[handler.py]"]
  node_request["Request context<br/>[request.py]"]
  node_response["Gemini response<br/>[response.py]"]
end

subgraph group_resources["Resource handling"]
  node_registry["Resource registry"]
  node_filesystem["Filesystem resource<br/>[resource.py]"]
  node_metadata["File metadata<br/>[resource.py]"]
  node_cgi["CGI execution<br/>[resource.py]"]
  node_path_utils["Path normalization<br/>[util.py]"]
  node_mime["MIME handling<br/>[mime.py]"]
end

subgraph group_extensions["Bundled extensions"]
  node_pydoc["Python doc browser<br/>[pydoc.py]"]
  node_redirect["Redirect generator<br/>[redirect.py]"]
end

node_client(("Gemini client"))
node_python(("Python environment"))

node_client -->|"opens Gemini connection"| node_server_runtime
node_manager -->|"loads configuration"| node_config
node_manager -->|"starts server"| node_server_runtime
node_server_runtime -->|"creates TLS context"| node_tls
node_server_runtime -->|"dispatches request"| node_handler
node_server_runtime -->|"builds connection"| node_request
node_handler -->|"normalizes paths"| node_path_utils
node_handler -.->|"selects resource"| node_registry
node_handler -->|"invokes resource"| node_filesystem
node_filesystem -->|"loads metadata"| node_metadata
node_filesystem -->|"resolves paths"| node_path_utils
node_filesystem -->|"runs eligible scripts"| node_cgi
node_filesystem -->|"determines content type"| node_mime
node_filesystem -->|"creates response"| node_response
node_cgi -->|"creates response"| node_response
node_pydoc -->|"inspects modules"| node_python
node_pydoc -->|"creates response"| node_response
node_redirect -->|"creates response"| node_response
node_server_runtime -->|"writes response"| node_response

click node_server_runtime "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/server.py"
click node_tls "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/tls.py"
click node_config "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/config.py"
click node_manager "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/kindergarten.py"
click node_handler "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/handler.py"
click node_request "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/request.py"
click node_response "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/response.py"
click node_registry "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource_registry.py"
click node_filesystem "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py"
click node_metadata "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py"
click node_cgi "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py"
click node_path_utils "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/util.py"
click node_mime "https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/mime.py"
click node_pydoc "https://github.com/an-empty-string/amethyst/blob/main/amethyst_extensions/amethyst_ext/pydoc.py"
click node_redirect "https://github.com/an-empty-string/amethyst/blob/main/amethyst_extensions/amethyst_ext/redirect.py"

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_server_runtime,node_tls,node_config,node_manager,node_handler,node_request,node_response,node_client toneBlue
class node_registry,node_filesystem,node_metadata,node_cgi,node_path_utils,node_mime toneAmber
class node_pydoc,node_redirect toneMint
class node_python toneIndigo
```

## Components

### Gemini server

- [Connection server](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/server.py): `amethyst/amethyst/server.py`
- [TLS and SNI](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/tls.py): `amethyst/amethyst/tls.py`
- [Server configuration](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/config.py): `amethyst/amethyst/config.py`
- [Server manager](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/kindergarten.py): `amethyst/amethyst/kindergarten.py`
- [Generic handler](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/handler.py): `amethyst/amethyst/handler.py`
- [Request context](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/request.py): `amethyst/amethyst/request.py`
- [Gemini response](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/response.py): `amethyst/amethyst/response.py`

### Resource handling

- [Resource registry](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource_registry.py): `amethyst/amethyst/resource_registry.py`
- [Filesystem resource](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py): `amethyst/amethyst/resource.py`
- [File metadata](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py): `amethyst/amethyst/resource.py`
- [CGI execution](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/resource.py): `amethyst/amethyst/resource.py`
- [Path normalization](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/util.py): `amethyst/amethyst/util.py`
- [MIME handling](https://github.com/an-empty-string/amethyst/blob/main/amethyst/amethyst/mime.py): `amethyst/amethyst/mime.py`

### Bundled extensions

- [Python doc browser](https://github.com/an-empty-string/amethyst/blob/main/amethyst_extensions/amethyst_ext/pydoc.py): `amethyst_extensions/amethyst_ext/pydoc.py`
- [Redirect generator](https://github.com/an-empty-string/amethyst/blob/main/amethyst_extensions/amethyst_ext/redirect.py): `amethyst_extensions/amethyst_ext/redirect.py`

### Other components

- **Gemini client**
- **Python environment**

## Connections

- Gemini client → Connection server: opens Gemini connection
- Server manager → Server configuration: loads configuration
- Server manager → Connection server: starts server
- Connection server → TLS and SNI: creates TLS context
- Connection server → Generic handler: dispatches request
- Connection server → Request context: builds connection
- Generic handler → Path normalization: normalizes paths
- Generic handler → Resource registry: selects resource
- Generic handler → Filesystem resource: invokes resource
- Filesystem resource → File metadata: loads metadata
- Filesystem resource → Path normalization: resolves paths
- Filesystem resource → CGI execution: runs eligible scripts
- Filesystem resource → MIME handling: determines content type
- Filesystem resource → Gemini response: creates response
- CGI execution → Gemini response: creates response
- Python doc browser → Python environment: inspects modules
- Python doc browser → Gemini response: creates response
- Redirect generator → Gemini response: creates response
- Connection server → Gemini response: writes response