# ahmia/ahmia-site architecture

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

## Overview

Ahmia is a Django web search engine for .onion domains; crawling and index maintenance are handled by the separately documented ahmia-crawler and ahmia-index services. The main user workflow routes a search request to the results view, queries Elasticsearch, filters/formats hits, and renders a results page. Separate branches support onion submissions, domain listings, blacklist/help handling, and safe redirects. Source excerpts are partial, so links between views and unsampled model or template details are limited to what the tree, README, and excerpts support.

Main entry points: [`ahmia/views.py`](https://github.com/ahmia/ahmia-site/blob/master/ahmia/views.py) (Request views), [`ahmia/models.py`](https://github.com/ahmia/ahmia-site/blob/master/ahmia/models.py) (Domain records), [`ahmia/urls.py`](https://github.com/ahmia/ahmia-site/blob/master/ahmia/urls.py) (URL routes), [`ahmia/validators.py`](https://github.com/ahmia/ahmia-site/blob/master/ahmia/validators.py) (Search client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_routes["URL routes<br/>[urls.py]"]
  node_views["Request views<br/>[views.py]"]
  node_pages["Page templates"]
end

subgraph group_search["Search and index"]
  node_settings["Search configuration<br/>[settings.py]"]
  node_esclient["Search client<br/>[validators.py]"]
  node_elasticsearch[("Elasticsearch index")]
  node_crawler["Ahmia crawler"]
end

subgraph group_safety["Safety and submissions"]
  node_forms["Submission form<br/>[forms.py]"]
  node_validators["URL validators<br/>[validators.py]"]
  node_addcommand["Detection importer"]
end

subgraph group_state["Application state"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("Relational database")]
  node_deletecommand["Submission cleanup<br/>[deleteonions.py]"]
end

node_user(("Visitor"))

node_user -->|"sends request"| node_routes
node_routes -->|"dispatches"| node_views
node_views -->|"renders"| node_pages
node_views -->|"uses"| node_forms
node_forms -->|"validates with"| node_validators
node_validators -->|"checks banned status"| node_elasticsearch
node_views -->|"searches"| node_elasticsearch
node_settings -->|"configures"| node_esclient
node_esclient -->|"connects to"| node_elasticsearch
node_views -->|"reads and writes"| node_models
node_models -->|"persists"| node_database
node_addcommand -->|"imports domains"| node_models
node_deletecommand -->|"deletes submissions"| node_models
node_crawler -.->|"indexes crawl data"| node_elasticsearch

click node_routes "https://github.com/ahmia/ahmia-site/blob/master/ahmia/urls.py"
click node_views "https://github.com/ahmia/ahmia-site/blob/master/ahmia/views.py"
click node_pages "https://github.com/ahmia/ahmia-site/tree/master/ahmia/templates"
click node_forms "https://github.com/ahmia/ahmia-site/blob/master/ahmia/forms.py"
click node_validators "https://github.com/ahmia/ahmia-site/blob/master/ahmia/validators.py"
click node_models "https://github.com/ahmia/ahmia-site/blob/master/ahmia/models.py"
click node_settings "https://github.com/ahmia/ahmia-site/blob/master/ahmia/settings.py"
click node_esclient "https://github.com/ahmia/ahmia-site/blob/master/ahmia/validators.py"
click node_addcommand "https://github.com/ahmia/ahmia-site/blob/master/ahmia/management/commands/importcsamdetections.py"
click node_deletecommand "https://github.com/ahmia/ahmia-site/blob/master/ahmia/management/commands/deleteonions.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_routes,node_views,node_pages toneBlue
class node_settings,node_esclient,node_elasticsearch,node_crawler toneAmber
class node_forms,node_validators,node_addcommand toneMint
class node_models,node_database,node_deletecommand toneRose
class node_user toneIndigo
```

## Components

### Web interface

- [URL routes](https://github.com/ahmia/ahmia-site/blob/master/ahmia/urls.py): `ahmia/urls.py`
- [Request views](https://github.com/ahmia/ahmia-site/blob/master/ahmia/views.py): `ahmia/views.py`
- [Page templates](https://github.com/ahmia/ahmia-site/tree/master/ahmia/templates): `ahmia/templates`

### Search and index

- [Search configuration](https://github.com/ahmia/ahmia-site/blob/master/ahmia/settings.py): `ahmia/settings.py`
- [Search client](https://github.com/ahmia/ahmia-site/blob/master/ahmia/validators.py): `ahmia/validators.py`
- **Elasticsearch index**
- **Ahmia crawler**

### Safety and submissions

- [Submission form](https://github.com/ahmia/ahmia-site/blob/master/ahmia/forms.py): `ahmia/forms.py`
- [URL validators](https://github.com/ahmia/ahmia-site/blob/master/ahmia/validators.py): `ahmia/validators.py`
- [Detection importer](https://github.com/ahmia/ahmia-site/blob/master/ahmia/management/commands/importcsamdetections.py): `ahmia/management/commands/importcsamdetections.py`

### Application state

- [Domain records](https://github.com/ahmia/ahmia-site/blob/master/ahmia/models.py): `ahmia/models.py`
- **Relational database**
- [Submission cleanup](https://github.com/ahmia/ahmia-site/blob/master/ahmia/management/commands/deleteonions.py): `ahmia/management/commands/deleteonions.py`

### Other components

- **Visitor**

## Connections

- Visitor → URL routes: sends request
- URL routes → Request views: dispatches
- Request views → Page templates: renders
- Request views → Submission form: uses
- Submission form → URL validators: validates with
- URL validators → Elasticsearch index: checks banned status
- Request views → Elasticsearch index: searches
- Search configuration → Search client: configures
- Search client → Elasticsearch index: connects to
- Request views → Domain records: reads and writes
- Domain records → Relational database: persists
- Detection importer → Domain records: imports domains
- Submission cleanup → Domain records: deletes submissions
- Ahmia crawler → Elasticsearch index: indexes crawl data