docs: add architecture and a prop drilling adr

Author: gadomski

README.md

@@ -50,6 +50,7 @@ yarn test
 
 ## Contributing
 
+We have some [architecture documentation](./docs/architecture.md) to help you get the lay of the land.
 We use Github [Pull Requests](https://github.com/developmentseed/stac-map/pulls) to propose changes, and [Issues](https://github.com/developmentseed/stac-map/issues) to report bugs and request features.
 
 We use [semantic-release](https://github.com/semantic-release/semantic-release?tab=readme-ov-file) to create [releases](https://github.com/developmentseed/stac-map/releases).

docs/architecture.md

@@ -0,0 +1,45 @@
+# Architecture
+
+What follows is some light documentation on how **stac-map** is built.
+
+## Core concepts
+
+Here's the two core concepts of **stac-map**.
+
+### Everything starts with the `href`
+
+**stac-map** is driven by one (and only one) `href` value, which is a URI to a remote file _or_ the name of an uploaded file.
+The `href` is stored in the app state and is synchronized with a URL parameter, which allows the sharing of links to **stac-map** pointed at a specific STAC value.
+
+### The value could be (almost) anything
+
+Once the `href` is set, the data at the `href` is loaded into the app as a single `value`.
+The `value` could be:
+
+- A STAC [Catalog](https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md), [Collection](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md), or [Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md)
+- A STAC [API](https://github.com/radiantearth/stac-api-spec)
+- A GeoJSON [FeatureCollection](https://datatracker.ietf.org/doc/html/rfc7946#section-3.3) with STAC Items as its `features` (commonly referred to as an `ItemCollection`, though no such term exists in the STAC specification)
+- A [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet) file, which is treated as an `ItemCollection`.
+
+The behaviors of the app are then driven by the attributes of the `value`.
+
+## Concept diagram
+
+Any values that don't have a parent are set by the user, either directly (e.g. `href`) or by interacting with the app (e.g. `bbox`).
+
+```mermaid
+flowchart TD
+    h[href] --> value;
+    value --> catalogs;
+    value --> collections;
+    collections --> filteredCollections;
+    bbox --> filteredCollections;
+    datetimeBounds --> filteredCollections;
+    value --> linkedItems;
+    linkedItems -- if no user items --> items;
+    search --> userItems;
+    userItems --> items;
+    items --> filteredItems;
+    bbox --> filteredItems;
+    datetimeBounds --> filteredItems;
+```

docs/decisions/0002-drill-the-props.md

@@ -0,0 +1,23 @@
+# Drill the props
+
+## Context and Problem Statement
+
+There's a lot of state that we need to synchronize between the map and the rest of the application.
+
+## Considered Options
+
+- Use a custom context and provider
+- Use dispatch
+- Use a state management framework
+- Just [prop drill](https://react.dev/learn/passing-data-deeply-with-context#the-problem-with-passing-props)
+
+## Decision Outcome
+
+We tried both dispatch and a custom context, and while both were fine, they felt complicated to manage as the app changed state.
+We rejected a state management framework as "too heavy" for this simple of an app.
+As of v0.7, we went back to prop drilling.
+
+### Consequences
+
+- Good, because it encourages us to have a flatter, simpler component hierarchy
+- Bad, because it leads to components with _lots_ of props at a high level