# mozilla/ichnaea architecture

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

- Interactive diagram: https://gitdiagram.com/mozilla/ichnaea
- Repository: https://github.com/mozilla/ichnaea

## Overview

Ichnaea is the archived Mozilla Location Services backend: it accepts location queries and observation submissions, maintains radio-station data, and serves data and statistics. The tree and excerpts support the background-task dispatch and parts of the query/model layers; they do not show the full web routing or locate/submit execution path. Dashed locate links indicate unverified relationships rather than confirmed calls.

Main entry points: [`ichnaea/data/tasks.py`](https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/tasks.py) (Scheduled tasks), [`ichnaea/api/locate/searcher.py`](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/searcher.py) (Location search), [`ichnaea/api/submit/views.py`](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/submit/views.py) (Observation submission), [`ichnaea/models/observation.py`](https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/observation.py) (Report models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Location API"]
  node_locate["Locate endpoint<br/>[views.py]"]
  node_query["Query validation<br/>[query.py]"]
  node_searcher["Location search<br/>[searcher.py]"]
  node_fallback["Fallback lookup<br/>[fallback.py]"]
  node_geoip["GeoIP lookup<br/>[geoip.py]"]
  node_internal["Internal lookup<br/>[internal.py]"]
  node_result["Location result<br/>[result.py]"]
  node_submit["Observation submission<br/>[views.py]"]
end

subgraph group_data["Observation Data"]
  node_observations["Report models<br/>[observation.py]"]
  node_stations["Station models<br/>[station.py]"]
  node_radio["Radio network models<br/>[cell.py]"]
  node_db[("Database access<br/>[db.py]")]
end

subgraph group_background["Background Processing"]
  node_taskapp["Task runtime<br/>[app.py]"]
  node_tasks["Scheduled tasks<br/>[tasks.py]"]
  node_station_updates["Station updates<br/>[station.py]"]
end

subgraph group_public["Data and Content"]
  node_exports["Data exports<br/>[export.py]"]
  node_public_data["Public datasets<br/>[public.py]"]
  node_monitor["Usage monitoring<br/>[monitor.py]"]
  node_content["Content and statistics<br/>[views.py]"]
end

node_client(("API client"))

node_client -.->|"requests location"| node_locate
node_client -.->|"submits reports"| node_submit
node_query -.->|"provides query"| node_searcher
node_searcher -.->|"uses lookup"| node_fallback
node_searcher -.->|"uses lookup"| node_geoip
node_searcher -.->|"uses lookup"| node_internal
node_searcher -.->|"uses result"| node_result
node_submit -.->|"validates reports"| node_observations
node_taskapp -.->|"runs tasks"| node_tasks
node_tasks -->|"dispatches updates"| node_station_updates
node_tasks -->|"dispatches exports"| node_exports
node_tasks -->|"dispatches exports"| node_public_data
node_tasks -->|"dispatches monitoring"| node_monitor
node_tasks -.->|"dispatches statistics"| node_content
node_station_updates -->|"accesses database"| node_db
node_observations -->|"uses radio types"| node_radio

click node_locate "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/views.py"
click node_query "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/query.py"
click node_searcher "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/searcher.py"
click node_fallback "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/fallback.py"
click node_geoip "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/geoip.py"
click node_internal "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/internal.py"
click node_result "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/result.py"
click node_submit "https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/submit/views.py"
click node_observations "https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/observation.py"
click node_stations "https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/station.py"
click node_radio "https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/cell.py"
click node_db "https://github.com/mozilla/ichnaea/blob/main/ichnaea/db.py"
click node_taskapp "https://github.com/mozilla/ichnaea/blob/main/ichnaea/taskapp/app.py"
click node_tasks "https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/tasks.py"
click node_station_updates "https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/station.py"
click node_exports "https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/export.py"
click node_public_data "https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/public.py"
click node_monitor "https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/monitor.py"
click node_content "https://github.com/mozilla/ichnaea/blob/main/ichnaea/content/views.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_locate,node_query,node_searcher,node_fallback,node_geoip,node_internal,node_result,node_submit,node_client toneBlue
class node_observations,node_stations,node_radio,node_db toneAmber
class node_taskapp,node_tasks,node_station_updates toneMint
class node_exports,node_public_data,node_monitor,node_content toneRose
```

## Components

### Location API

- [Locate endpoint](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/views.py): `ichnaea/api/locate/views.py`
- [Query validation](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/query.py): `ichnaea/api/locate/query.py`
- [Location search](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/searcher.py): `ichnaea/api/locate/searcher.py`
- [Fallback lookup](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/fallback.py): `ichnaea/api/locate/fallback.py`
- [GeoIP lookup](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/geoip.py): `ichnaea/api/locate/geoip.py`
- [Internal lookup](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/internal.py): `ichnaea/api/locate/internal.py`
- [Location result](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/locate/result.py): `ichnaea/api/locate/result.py`
- [Observation submission](https://github.com/mozilla/ichnaea/blob/main/ichnaea/api/submit/views.py): `ichnaea/api/submit/views.py`

### Observation Data

- [Report models](https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/observation.py): `ichnaea/models/observation.py`
- [Station models](https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/station.py): `ichnaea/models/station.py`
- [Radio network models](https://github.com/mozilla/ichnaea/blob/main/ichnaea/models/cell.py): `ichnaea/models/cell.py`
- [Database access](https://github.com/mozilla/ichnaea/blob/main/ichnaea/db.py): `ichnaea/db.py`

### Background Processing

- [Task runtime](https://github.com/mozilla/ichnaea/blob/main/ichnaea/taskapp/app.py): `ichnaea/taskapp/app.py`
- [Scheduled tasks](https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/tasks.py): `ichnaea/data/tasks.py`
- [Station updates](https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/station.py): `ichnaea/data/station.py`

### Data and Content

- [Data exports](https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/export.py): `ichnaea/data/export.py`
- [Public datasets](https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/public.py): `ichnaea/data/public.py`
- [Usage monitoring](https://github.com/mozilla/ichnaea/blob/main/ichnaea/data/monitor.py): `ichnaea/data/monitor.py`
- [Content and statistics](https://github.com/mozilla/ichnaea/blob/main/ichnaea/content/views.py): `ichnaea/content/views.py`

### Other components

- **API client**

## Connections

- API client → Locate endpoint: requests location
- API client → Observation submission: submits reports
- Query validation → Location search: provides query
- Location search → Fallback lookup: uses lookup (evidence: `ichnaea/api/locate/searcher.py`)
- Location search → GeoIP lookup: uses lookup (evidence: `ichnaea/api/locate/searcher.py`)
- Location search → Internal lookup: uses lookup (evidence: `ichnaea/api/locate/searcher.py`)
- Location search → Location result: uses result (evidence: `ichnaea/api/locate/searcher.py`)
- Observation submission → Report models: validates reports
- Task runtime → Scheduled tasks: runs tasks (evidence: `ichnaea/data/tasks.py`)
- Scheduled tasks → Station updates: dispatches updates (evidence: `ichnaea/data/tasks.py`)
- Scheduled tasks → Data exports: dispatches exports (evidence: `ichnaea/data/tasks.py`)
- Scheduled tasks → Public datasets: dispatches exports (evidence: `ichnaea/data/tasks.py`)
- Scheduled tasks → Usage monitoring: dispatches monitoring (evidence: `ichnaea/data/tasks.py`)
- Scheduled tasks → Content and statistics: dispatches statistics
- Station updates → Database access: accesses database (evidence: `ichnaea/data/station.py`)
- Report models → Radio network models: uses radio types (evidence: `ichnaea/models/observation.py`)
