# geo_genius v0.2.0 - Table of Contents

> A versioned catalog of named geographic areas for Elixir and PostgreSQL/PostGIS applications

## Pages

- [GeoGenius](readme.md)
- [Installation and host integration](installation.md)
- [Reading the catalog](reading.md)
- [Ingesting a collection](ingestion.md)
- [Projections: keeping a source's own columns](projections.md)
- [SQL API reference](sql_api.md)
- [GeoGenius Design](geo-genius-design.md)
- [Changelog](changelog.md)

## Modules

- [GeoGenius](GeoGenius.md): A versioned catalog of named geographic areas for Elixir and
PostgreSQL/PostGIS applications.

- [GeoGenius.Migrations.V02](GeoGenius.Migrations.V02.md): Repaired display geometry on both boundary writes.
- [GeoGenius.Pipeline.Relate](GeoGenius.Pipeline.Relate.md): The import phase that rebuilds measured relations and writes every edge a
provider asserts.
- [GeoGenius.PostgresTypes](GeoGenius.PostgresTypes.md): A Postgrex types module registering the PostGIS extension, for hosts that do
not already define one.
- [GeoGenius.Providers.CSV.Parsers.Pipe](GeoGenius.Providers.CSV.Parsers.Pipe.md): NimbleCSV parser for a pipe-delimited artifact, defined once at compile time.
- [GeoGenius.Providers.CSV.Parsers.Semicolon](GeoGenius.Providers.CSV.Parsers.Semicolon.md): NimbleCSV parser for a semicolon-delimited artifact, defined once at compile time.
- [GeoGenius.Providers.CSV.Parsers.Tab](GeoGenius.Providers.CSV.Parsers.Tab.md): NimbleCSV parser for a tab-delimited artifact, defined once at compile time.
- [GeoGenius.Providers.Delimited](GeoGenius.Providers.Delimited.md): Streams a delimited artifact in chunks, reading its first line as the
header row and handing each data line to the provider's own row builder.
- [GeoGenius.Providers.GeoJSONGeometry](GeoGenius.Providers.GeoJSONGeometry.md): Decodes the optional `"geometry"` member shared by GeoJSON Feature readers.

- [GeoGenius.Providers.ImpliedAreas](GeoGenius.Providers.ImpliedAreas.md): Areas a source row implies through columns other than its own code.
- [GeoGenius.Providers.SimpleMaps](GeoGenius.Providers.SimpleMaps.md): The SimpleMaps US cities and ZIP codes datasets.
- [GeoGenius.Providers.SimpleMaps.Fips](GeoGenius.Providers.SimpleMaps.Fips.md): The state a county FIPS code is assigned within.
- [GeoGenius.Providers.SimpleMaps.Rows](GeoGenius.Providers.SimpleMaps.Rows.md): Turns one staged SimpleMaps row into the areas it describes.
- [GeoGenius.Providers.SimpleMaps.Validation](GeoGenius.Providers.SimpleMaps.Validation.md): Row-scoped consistency checks for SimpleMaps' denormalised county columns.
- [GeoGenius.Staging.Row](GeoGenius.Staging.Row.md): One staged record.

- Reading
  - [GeoGenius.AreaMatch](GeoGenius.AreaMatch.md): One area returned by a catalog read, with whatever the read measured about it.
  - [GeoGenius.Preflight](GeoGenius.Preflight.md): Verifies GeoGenius's database prerequisites and fails host startup when they
are not met.
  - [GeoGenius.Published](GeoGenius.Published.md): Composable Ecto queries over the catalog's read views.
  - [GeoGenius.Published.Area](GeoGenius.Published.Area.md): One area of a release, as `published_areas` and its release-scoped base
`release_areas` project it.
  - [GeoGenius.Published.AreaCode](GeoGenius.Published.AreaCode.md): One external code held by an area of a release, as `published_area_codes`
and its release-scoped base `release_area_codes` project it.
  - [GeoGenius.Published.AreaName](GeoGenius.Published.AreaName.md): One name held by an area of a release, as `published_area_names` and its
release-scoped base `release_area_names` project it.
  - [GeoGenius.Published.AreaRelation](GeoGenius.Published.AreaRelation.md): One parent-to-child edge among areas of a release, as
`published_area_relations` and its release-scoped base `release_relations`
project it.
  - [GeoGenius.Query](GeoGenius.Query.md): Composable Ecto queries over the catalog's read functions.
  - [GeoGenius.ReleaseArtifacts](GeoGenius.ReleaseArtifacts.md): What files a release was built from, and where each one is on this machine.
  - [GeoGenius.ReleaseArtifacts.Artifact](GeoGenius.ReleaseArtifacts.Artifact.md): One artifact a release composes, together with where it resolves to on this
machine.
  - [GeoGenius.SeededMatch](GeoGenius.SeededMatch.md): One area returned by a plural catalog read, paired with the seed that found
it.

- Ingestion
  - [GeoGenius.ImportRun](GeoGenius.ImportRun.md): One import run, as the `import_run_status` view reports it.
  - [GeoGenius.Manifest](GeoGenius.Manifest.md): The reviewed document that describes one release: `<manifest_dir>/<collection>/<release>.json`.
  - [GeoGenius.Manifest.Artifact](GeoGenius.Manifest.Artifact.md): One file (or archive) a source is built from.
  - [GeoGenius.Manifest.Source](GeoGenius.Manifest.Source.md): One data source within a release: where it comes from, how it is licensed,
and the artifacts that carry it.
  - [GeoGenius.Pipeline](GeoGenius.Pipeline.md): Turns a claimed import run into a verified release.
  - [GeoGenius.Registration](GeoGenius.Registration.md): Translates the catalog's exact-candidate lifecycle decision into the public
Elixir result vocabulary.

- Catalog
  - [GeoGenius.Catalog](GeoGenius.Catalog.md): Writes and publishes the catalog: collections, authorities, area types,
areas, their names and codes, releases, sources, artifacts, and import
runs.
  - [GeoGenius.Context](GeoGenius.Context.md): Runtime dependencies for one GeoGenius operation.
  - [GeoGenius.Staging](GeoGenius.Staging.md): The per-run landing area between an artifact and the catalog.

- Extension points
  - [GeoGenius.Cache](GeoGenius.Cache.md): Where downloaded and operator-supplied artifacts live between runs.
  - [GeoGenius.Command](GeoGenius.Command.md): Behaviour for invoking an external executable.
  - [GeoGenius.Downloader](GeoGenius.Downloader.md): Behaviour for fetching a remote artifact to a local path.
  - [GeoGenius.Notifier](GeoGenius.Notifier.md): Behaviour for delivering import lifecycle events to a host application.
  - [GeoGenius.Provider](GeoGenius.Provider.md): Behaviour a format adapter implements to bring one kind of source into the catalog.
  - [GeoGenius.Provider.Area](GeoGenius.Provider.Area.md): The whole vocabulary a provider has for describing one area.
  - [GeoGenius.Provider.Area.Code](GeoGenius.Provider.Area.Code.md): One external code a `GeoGenius.Provider.Area` carries, such as a FIPS or
GNIS identifier.
  - [GeoGenius.Provider.Area.Name](GeoGenius.Provider.Area.Name.md): One name a `GeoGenius.Provider.Area` carries.
  - [GeoGenius.Runner](GeoGenius.Runner.md): Behaviour for backends that start a claimed import run.
  - [GeoGenius.Store](GeoGenius.Store.md): The contract every catalog read goes through.

- Shipped adapters
  - [GeoGenius.Caches.FileSystem](GeoGenius.Caches.FileSystem.md): The shipped `GeoGenius.Cache`: artifacts stored as plain files under one
root directory.
  - [GeoGenius.Commands.System](GeoGenius.Commands.System.md): Runs external executables via `System.cmd/3`.
  - [GeoGenius.Downloaders.Req](GeoGenius.Downloaders.Req.md): Streams an artifact to disk with Req, hashing as it goes.
  - [GeoGenius.Notifiers.Noop](GeoGenius.Notifiers.Noop.md): The shipped notifier for a host that has not configured one of its own.
  - [GeoGenius.Providers.CSV](GeoGenius.Providers.CSV.md): Provider for a single delimited-text artifact with a header row.
  - [GeoGenius.Providers.GeoJSON](GeoGenius.Providers.GeoJSON.md): Provider for a single GeoJSON `FeatureCollection` artifact.
  - [GeoGenius.Providers.GeoJSONSequence](GeoGenius.Providers.GeoJSONSequence.md): Streams newline- or RFC 8142 record-separator-delimited GeoJSON Features.
  - [GeoGenius.Providers.Shapefile](GeoGenius.Providers.Shapefile.md): Provider for a shapefile archive.
  - [GeoGenius.Runners.Inline](GeoGenius.Runners.Inline.md): Runs an import in the calling process.
  - [GeoGenius.Runners.PgFlow](GeoGenius.Runners.PgFlow.md): Runs an import as a durable PgFlow background job.
  - [GeoGenius.Runners.Task](GeoGenius.Runners.Task.md): Runs an import under a `Task.Supervisor`.
  - [GeoGenius.Stores.Postgres](GeoGenius.Stores.Postgres.md): Every read is one call to a SQL function in the installed schema, with every
optional argument bound explicitly, so a read never inherits a default from
the database that differs from the one the library documents.

- Installation
  - [GeoGenius.Migration](GeoGenius.Migration.md): Versioned GeoGenius schema migrations for host applications.
  - [GeoGenius.Migrations.V01](GeoGenius.Migrations.V01.md): Initial prefix-safe GeoGenius catalog schema.

- Exceptions
  - [GeoGenius.ArtifactError](GeoGenius.ArtifactError.md): Raised when a release's artifacts cannot be listed, or one of them cannot be
resolved to a file on this machine.
  - [GeoGenius.CandidateError](GeoGenius.CandidateError.md): A structured refusal from the exact import-candidate lifecycle.
  - [GeoGenius.CatalogError](GeoGenius.CatalogError.md): Raised when a `GeoGenius.Catalog` call cannot be completed.
  - [GeoGenius.EnqueueError](GeoGenius.EnqueueError.md): A structured failure to confirm an import runner enqueue.
  - [GeoGenius.ImportError](GeoGenius.ImportError.md): Raised when an import run cannot continue.
  - [GeoGenius.ManifestError](GeoGenius.ManifestError.md): Raised when a manifest cannot be read, decoded, or validated.
  - [GeoGenius.PreflightError](GeoGenius.PreflightError.md): Raised when the database does not satisfy GeoGenius's prerequisites at startup.

  - [GeoGenius.QueryError](GeoGenius.QueryError.md): Raised when a reading call through `GeoGenius.Store` cannot be completed.
  - [GeoGenius.StagingError](GeoGenius.StagingError.md): Raised when a staging table cannot be written to or read from.

- Internal
  - [GeoGenius.Application](GeoGenius.Application.md): Starts GeoGenius's own supervision tree: an execution-guardian supervisor
and, unless a host supplies one, a `Task.Supervisor` registered as
`GeoGenius.TaskSupervisor`.
  - [GeoGenius.Bootstrap](GeoGenius.Bootstrap.md): Optional supervised child that idempotently enqueues a configured desired
release at host boot.
  - [GeoGenius.Files](GeoGenius.Files.md): Filesystem helpers shared by manifest loading and the providers that read
staged artifacts from disk.
  - [GeoGenius.Pipeline.Artifacts](GeoGenius.Pipeline.Artifacts.md): The import phases that obtain a release's files: `download/1` and
`validate/1`.
  - [GeoGenius.Pipeline.CommandAllowlist](GeoGenius.Pipeline.CommandAllowlist.md): The `GeoGenius.Command` the import pipeline hands a provider: the configured
command adapter, narrowed to the one executable a shipped provider needs.
  - [GeoGenius.Pipeline.Normalize](GeoGenius.Pipeline.Normalize.md): The import phase that turns staged rows into catalog rows.
  - [GeoGenius.Pipeline.State](GeoGenius.Pipeline.State.md): One run's working set, threaded through every phase.
  - [GeoGenius.Providers.Batch](GeoGenius.Providers.Batch.md): Turns a list of raw items into staged rows, one `fun` call per item,
stopping at the first error.
  - [GeoGenius.Providers.Fields](GeoGenius.Providers.Fields.md): Coerces a raw payload value -- read out of a GeoJSON feature's properties
or a CSV row's cells -- into either a present string or `nil`.
  - [GeoGenius.Providers.ManifestOptions](GeoGenius.Providers.ManifestOptions.md): Manifest `options` lookups and payload-field extraction shared by every
provider that reads a code, names, attributes, and external codes out of
a manifest and a staged payload the way `GeoGenius.Providers.GeoJSON` and
`GeoGenius.Providers.CSV` both do.
  - [GeoGenius.ResultMapper](GeoGenius.ResultMapper.md): Maps a `Postgrex.Result` into structs by column name.
  - [GeoGenius.Telemetry](GeoGenius.Telemetry.md): Telemetry events GeoGenius emits.

## Mix Tasks

- Mix tasks
  - [mix geo_genius.check_schema](Mix.Tasks.GeoGenius.CheckSchema.md): Checks that the installed GeoGenius schema version matches the version
shipped by this package.
  - [mix geo_genius.gen.migration](Mix.Tasks.GeoGenius.Gen.Migration.md): Generates a pinned wrapper for one supported adjacent GeoGenius schema upgrade.
  - [mix geo_genius.import](Mix.Tasks.GeoGenius.Import.md): Registers a collection release from its manifest and enqueues its import.
  - [mix geo_genius.migration_sql](Mix.Tasks.GeoGenius.MigrationSql.md): Renders a pinned GeoGenius SQL transition for non-Ecto migration hosts.
  - [mix geo_genius.publish](Mix.Tasks.GeoGenius.Publish.md): Publishes a verified release, so reads that name no release id resolve to it.
  - [mix geo_genius.rollback](Mix.Tasks.GeoGenius.Rollback.md): Rolls a collection's publication back to its previous release.
  - [mix geo_genius.setup](Mix.Tasks.GeoGenius.Setup.md): Generates the host application's pinned initial GeoGenius migration wrapper.
  - [mix geo_genius.status](Mix.Tasks.GeoGenius.Status.md): Reports import runs, and what a collection currently publishes.
  - [mix geo_genius.sweep_staging](Mix.Tasks.GeoGenius.SweepStaging.md): Drops per-run staging tables left behind by runs that have already finished.
  - [mix geo_genius.uninstall](Mix.Tasks.GeoGenius.Uninstall.md): Drops the GeoGenius schema and all of its data at a prefix.