@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/intro.md

@@ -0,0 +1,149 @@
+---
+sidebar_position: 0
+---
+
+# Getting Started
+
+## Introduction
+
+Welcome to the Powerhouse Analytics Engine Documentation. This engine is a powerful time-series analytics system, written in Typescript with an optional GraphQL interface on top. It is designed to run _anywhere_. Browsers, server environments, CLI tools, etc.
+
+This documentation serves as a guide for Typescript and GraphQL API usage, not library development. For documentation on how to build or contribute to this project, see our [README](https://github.com/powerhouse-inc/analytics-engine/blob/main/README.md).
+
+## Overview
+
+![high-level](./images/high-level.jpg)
+
+This system can be broken up into several major systems: **queries**, **engine components** (including filters and aggregation), and **storage**. Each of these systems have detailed documentation, but it is most helpful to start with a holistic understanding of the major pieces of data: series and dimensions.
+
+### Series and Dimensions
+
+All metrics are collected and stored using only two objects: **AnalyticsSeries** and **AnalyticsDimension**. To be a successful consumer of this system, It is vital to understand the intent of these two pieces of data.
+
+![1](./images/overview-1.jpg)
+
+Typical time-series databases (like [Graphite](https://graphiteapp.org/)) usually store data as `(time, value)` tuples: relating an explicit value to an explicit time. In the Web3 space, we have learned through [real uses cases with MakerDAO](https://fusion.sky.money/), that this isn't quite flexible enough for Web3 constructs.
+
+Instead, the time series values in this system are given by a value paired with a _time interval_. That is, values have a start and an end. This allows for interpolation functions across a time interval, like a linear change.
+
+Of course, the default is simply a constant function, giving a constant value inside of the time interval.
+
+![4](./images/overview-4.jpg)
+
+This means that when we want to query data, we are querying over intervals and can query for either "running totals" or changes (deltas) over an interval.
+
+In the example above, querying over different intervals returns different totals and deltas depending on interval. This is another difference with typical time-series databases: deltas as first class. The analytics system takes care of this aggregation for users.
+
+![2](./images/overview-2.jpg)
+
+In real use cases, we generally have many data sets running in parallel. In this example, we have two related systems, both inserting data. Some of the intervals overlap, some don't, and we see some gaps in the data as well.
+
+![3](./images/overview-3.jpg)
+
+The question is: how do we query and aggregate this related data? We could potentially make multiple queries and do this ourselves, but it would require a good understanding of the implementation details.
+
+This is where the **AnalyticsDimension** object comes into play.
+
+![4](./images//overview-5.jpg)
+
+While there will be thousands or millions of series objects, there will be far fewer referenced dimension objects. Dimensions allow users to decorate series objects with query and aggregation information. These objects are shared across all the series records.
+
+Visually, you can think of series as values running up and down, while dimensions allow for query and aggregation _across_ the different series objects.
+
+![6](./images/overview-6.jpg)
+
+### Structure v Reporting
+
+The Series and Dimensions objects give control over how metric data is defined and related. That is, they define the **structure** of data. Three new concepts: Paths, LODs, and granularity, are parameters used to define how the system should _report_ the data.
+
+### Paths
+
+Let's start with paths. A `path` is a field on an `AnalyticsDimension` that describes the _specificity of the query_.
+
+![1](./images/paths-1.jpg)
+
+In this example, inspired by real MakerDAO metrics, we have a number of series values that have been decorated with a couple of dimensions. Dimensions, as we have discussed, have a name like "budget". They also have this `path` field, which looks like a URI or directory hierarchy: a string made up of smaller strings separated by `/`s.
+
+Note that, some series values have been decorated with multiple dimensions, some with a single dimension, and some have not been decorated with either.
+
+It's clear enough that when we request budget data for a specific MIP dimension, like the purple one (`/atlas/mip40/MIP40c3SP61`), we should be getting totals and deltas across only the purple series objects.
+
+But what if we want to query across everything related to `mip40`?
+
+![2](./images/paths-2.jpg)
+
+This is the beauty of dimension paths. All we need to do is use a `path` to describe the _specificity_ of the query. In this case, we use `/atlas/mip40`, which will match all dimensions that start with `/atlas/mip40`, which in turn matches all series values related to to those dimensions.
+
+### LODs
+
+`LOD` is short for "level of detail", and it is not a field found on either the series or dimension objects. It is a parameter used in queries only, to determine how results are aggregated across dimensions.
+
+Let's look at our example again.
+
+![a](./images/paths-2.jpg)
+
+Here we have asked for a report on the `budget` metric, with path `/atlast/mip40`. The path determines the specificity of the query, and LOD determines how to aggregate results.
+
+![lod](./images/lod.jpg)
+
+An LOD of `0` will group all results together in a single value. An LOD of `1` will group results by the first part of the path, in this case: `/atlas`. And so on for an LOD of 2 or 3. This means that increasing the LOD will increase the number of values retieved as the system needs to aggregate with higher specificity.
+
+An LOD greater than the number of parts of the path (in this case, 4 or more) will append a `/*` for each additional path part to the end of the grouped results but will provide the same results as the highest level of detail.
+
+### Granularity
+
+While LODs allow you to aggregate series data across dimensions, _granularity_ refers to how data is aggregated over time. It determines the time span each data point or record covers. Choosing the right granularity is crucial for meaningful analysis, as it affects the interpretation and insights that can be drawn from the data.
+
+#### Available Options
+
+The analytics engine supports various granularity options, each suitable for different types of analysis:
+
+1. `total`: Provides a cumulative view of data over the entire time frame available in the dataset. Best used for overall summaries and long-term analysis.
+
+2. `annual`: Aggregates data on a yearly basis. Ideal for year-over-year comparisons and annual trend analysis.
+
+3. `semiAnnual` : Breaks down data into six-month periods. Useful for understanding bi-annual trends and patterns.
+
+4. `quarterly`: Divides data into quarters, offering insights into seasonal trends or quarter-over-quarter performance.
+
+5. `monthly` : Monthly granularity is useful for a more detailed view of trends and patterns, particularly useful for operational planning and monitoring.
+
+6. `weekly` : Provides weekly data aggregation, which is helpful for short-term performance tracking and operational adjustments.
+daily: Offers a day-to-day breakdown, ideal for detailed analysis of daily operations or events.
+
+7. `hourly`: The most granular level, providing insights into hourly fluctuations. Useful in scenarios where short-term data spikes or dips are significant.
+
+#### How Granularity Affects Query Results
+
+- Data Volume: Higher granularity (like hourly or daily) results in a larger volume of data points, providing more detailed insights but potentially leading to more complex analysis. Lower granularity (like annual or total) simplifies the data into fewer, broader data points.
+
+- Trend Analysis: Finer granularity helps in identifying short-term trends and anomalies, whereas coarser granularity is better for long-term trend analysis and strategic planning.
+Performance Impact: Queries with finer granularity might be more resource-intensive and take longer to execute due to the larger number of data points processed.
+
+- Contextual Relevance: The choice of granularity should match the context of the analysis. For instance, financial planning might prefer annual or quarterly granularity, while operational monitoring might require daily or hourly data.
+
+- Comparative Analysis: Different granularity levels can be used for comparative analysis, such as comparing detailed daily data (through daily granularity) against broader monthly trends (using monthly granularity) to understand day-to-day variations within the context of a monthly overview.
+
+In summary, the choice of granularity in your query significantly influences the scope, detail, and utility of the analytics results. It is important to align the granularity with the specific analytical objectives and the nature of the data being analyzed to ensure that the insights derived are both relevant and actionable.
+
+## Cheatsheet
+
+These are high-level definitions of major terms you will need to know.
+
+* **AnalyticsSeries** - The individual metric values, comprised of `(value, start, end)`. There should be one of these for every change in value.
+
+* **AnalyticsDimension** - Shared objects that decorate series objects with `name` and `path` information. Used to relate metrics to one another.
+
+* **Path** - Composable, `/`-delimited string field on dimension that is used to _determine specificity_ during queries.
+
+* **LOD** - A number that, when paired with `path`, determines how to aggregate values across dimensions.
+
+* **Granularity** - Determines how to aggregate values over time, like "monthly" or "yearly".
+
+## Next Steps
+
+Next steps depend on use case.
+
+* For developers looking to **input data**, or **query data with Typescript**, see the [Typescript](./typescript/) docs.
+* For developers interested in **querying data with GraphQL**, see the [GraphQL](./graphql/) documentation. Data cannot be input through GraphQL.
+* For developers interested in **contributing to this project**, see the developer documentation [on GitHub](https://github.com/powerhouse-inc/analytics-engine).

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/benchmarks.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 102
+---
+
+# Benchmarks
+
+Due to the performance-sensitive nature of metrics collection, we include a [suite of benchmarks](https://github.com/powerhouse-inc/analytics-engine/tree/main/benchmarks) that compare the various analytics store implementations. These are run every publish and stored in the associated [GitHub action history](https://github.com/powerhouse-inc/analytics-engine/actions/runs/12123429624/job/33798972072).
+
+We also include results from major releases [here](https://github.com/powerhouse-inc/analytics-engine/tree/main/benchmarks/results).
+
+In summary, we have found that the `MemoryAnalyticsStore` and `PostgresAnalyticsStore` implementations are very close in performance, with the Postgres implementation slightly faster in most applications.
+
+## Query-list
+
+In [this benchmark](https://github.com/powerhouse-inc/analytics-engine/blob/main/benchmarks/results/query-list/), we ran the most frequent 600+ real-world queries against matching tables of around 200k records.
+
+We found that, on average, the `MemoryAnalyticsStore` implementation took about `1.36x` the time it took `PostgresAnalyticsStore`. Full results [here](https://github.com/powerhouse-inc/analytics-engine/blob/main/benchmarks/results/query-list/pglite.txt).
+
+## WASM
+
+In [this benchmark](https://github.com/powerhouse-inc/analytics-engine/blob/main/benchmarks/results/wasm/), we analyze the startup and insert time for the `MemoryAnalyticsStore` implementation.
+
+| Operation    | Ops per Sec | Average Time |
+| ------------ | ----------- | ------------ |
+| Init         | 3           | 323.00 ms    |
+| 100 Inserts  | 478         | 2.08 ms      |
+| 200k Inserts | 0           | 4448.10 ms   |

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/browser.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 2
+---
+
+# Browser Store
+
+The `BrowserAnalyticsStore` is an `IAnalyticsStore` implementation that sits on top of [`MemoryAnalyticsStore`](#memory) but adds an `IndexedDB` plugin for persistence.
+
+<aside class="notice">
+See the <a href="#compatibility">Compatibility</a> section for details on which stores are intended to be used in different execution environments.
+</aside>
+
+## Construction
+
+A default implementation of the `BrowserAnalyticsStore` may be created with no arguments, or options are provided for specialized needs.
+
+```typescript
+// creates a database named "analytics"
+const store = new BrowserAnalyticsStore();
+```
+
+> Create with a specific database name.
+
+```typescript
+const store = new BrowserAnalyticsStore({ databaseName: "analytics" });
+```
+
+> It may also be created with optional contructor arguments that may be helpful for debugging or metrics collection.
+
+```typescript
+const store = new BrowserAnalyticsStore({
+  databaseName: "analytics",
+
+  queryLogger: defaultQueryLogger("browser"),
+  resultsLogger: defaultResultsLogger("browser"),
+  profiler: new PassthroughAnalyticsProfiler(),
+});
+```
+
+For more details on these optional constructor parameters, see the [Utilities](#utilities) section.
+
+Since the constructor options argument extends the `MemoryAnalyticsStore` options argument, see the [`MemoryAnalyticsStore`](#memory) documentation for further details on other optional parameters.
+
+## Initialization
+
+Similar to the [`MemoryAnalyticsStore`](#memory), this implementation requires an asynchronous initialization step.
+
+> Note that this method is not available on the `IAnalyticsStore` interface, but only on the concrete type.
+
+```typescript
+// create the store
+const store = new BrowserAnalyticsStore();
+
+// initialize it
+await store.init();
+```
+
+## Persistence
+
+The `databaseName` constructor argument namespaces the database. This allows users to create multiple stores, if needed, which will not conflict with each other. You can use your browser's developer tools to see these databases, usually through the "Storage" tab.
+
+<aside class="notice">
+While manipulating the data manually is not recommended, this allows you to easily delete and recreate databases if needed.
+</aside>
+
+![dev-tools](../images/indexeddb.png)
+
+The store interface is intended to be immutable, meaning that it does not provide a general method of wiping a DB. However, an IDB database may be deleted via the standard [IDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
+
+```typescript
+// creates the database
+const store = new BrowserAnalyticsStore({ databaseName: "my-analytics" });
+await store.init();
+
+// use the browser API to delete the database
+window.indexedDB.deleteDatabase("my-analytics");
+```

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/compatibility.md

@@ -0,0 +1,14 @@
+---
+sidebar_position: 101
+---
+
+# Compatibility
+
+This guide is intended for making high level decisions about which storage systems to use in which contexts. These stores have not been tested across thousands of browser or serverside runtime versions.
+
+| Store                    | Browser | Node | Bun |
+| ------------------------ | ------- | ---- | --- |
+| `MemoryAnalyticsStore`   | X       | X    | X   |
+| `BrowserAnalyticsStore`  | X       |      |     |
+| `KnexAnalyticsStore`     | X       | X    | X   |
+| `PostgresAnalyticsStore` |         | X    | X   |

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/index.md

@@ -0,0 +1,230 @@
+---
+sidebar_position: 2
+---
+
+# Typescript API
+
+## Overview
+
+The analytics system is broken into several modules, allowing developers to deploy across many environments, for a diverse set of use cases.
+
+![libs](../images/libs.jpg)
+
+The `core` library contains common data types and abstractions used throughout. The job of the core library is to link together query, storage, and aggregation logic.
+
+![libs](../images/libs-core.jpg)
+
+The `knex`, `pg`, and `browser` libraries contain various storage implementations. Finally, the `graphql` library contains types, resolvers, and data types for a GraphQL API on top.
+
+## Querying Data
+
+The entry point for data queries in Typescript is the `AnalyticsQueryEngine`. This wraps an `IAnalyticsStore` implementation, which will be discussed in detail later.
+
+In this example, we create a simple in-memory storage engine, compatible with all platforms.
+
+```typescript
+import { AnalyticsQueryEngine } from "@powerhousedao/analytics-core";
+import { MemoryAnalyticsStore } from "@powerhousedao/analytics-memory";
+
+const engine = new AnalyticsQueryEngine(new MemoryAnalyticsStore());
+```
+
+### AnalyticsQuery
+
+Queries use the engine's `execute` function, taking an `AnalyticsQuery` parameter:
+
+```typescript
+type AnalyticsQuery = {
+  start: DateTime | null;
+  end: DateTime | null;
+  metrics: string[];
+  currency: AnalyticsPath;
+  select: Record<string, AnalyticsPath[]>;
+  granularity: AnalyticsGranularity;
+  lod: Record<string, number | null>;
+};
+```
+
+Each field plays a specific role in determining what data is returned by the analytics engine. Here's a clear and concise description of each:
+
+- `start`: This is the starting date and time of the series, using Luxon types. See the [note about times](#a-note-about-times) for more information.
+
+- `end`: This is the ending date and time of the series, using Luxon types. See the [note about times](#a-note-about-times) for more information.
+
+- `metrics`: Specifies the particular metrics being queried (e.g., `"budget"`). Each element will refer to the `name` field on the related [`AnalyticsDimension` objects](../intro.md#series-and-dimensions).
+
+- `currency`: A path reference to the currency to match (e.g. - `"usd"`).
+
+- `select`: This object is a map from metric name to a list of paths (e.g. - `{ budget: ["/atlas"] }`). These paths are used for matching via the [`AnalyticsDimension` objects](../intro.md#series-and-dimensions).
+
+- `granularity`: This field denotes the aggregation period for the data (e.g., `"monthly"`). A full list of options is available [here](../intro.md#granularity).
+
+- `lod`: A map from metric name to the level of detail parameter (e.g. - `3`), described in detail [here](../intro.md#lods).
+
+This query structure allows users to extract detailed and summarized analytics data. A full example will look like:
+
+```typescript
+const results = await engine.execute({
+  start: DateTime.fromIso("2020-01-01T00:00:00.000Z"),
+  end: "2100-01-01T00:00:00.000Z",
+  currency: AnalyticsPath.fromArray(["DAI"]),
+  metrics: ["Forecast"],
+  select: {
+    report: [AnalyticsPath.fromArray(["atlas", "EcosystemActor", "50", "2023", "11"])],
+  },
+  granularity: 0,
+  lod: {},
+});
+```
+
+This will return an array of `GroupedPeriodResult`.
+
+### GroupedPeriodResult
+
+This object is an aggregate. It represents a combined group of metrics over a time period.
+
+```typescript
+type GroupedPeriodResult = {
+  period: string;
+  start: DateTime;
+  end: DateTime;
+  rows: Array<{
+    dimensions: Record<string, AnalyticsDimension>;
+    metric: string;
+    unit: string | null;
+    value: number;
+    sum: number;
+  }>;
+};
+```
+
+- `period`: Within each series, this field denotes the aggregation period for the data (e.g., `"monthly"`), with a short description of which month, year, quarter, etc.
+
+- `start`: This is the starting date and time of the series, using Luxon types. See the [note about times](#a-note-about-times) for more information.
+
+- `end`: This is the ending date and time of the series, using Luxon types. See the [note about times](#a-note-about-times) for more information.
+
+- `rows`: Represents the individual records or entries in the data series. Each row corresponds to a unique combination of dimensions for the specified period.
+
+- `metric`: Within each row, this field specifies the particular metric being measured (e.g., `"budget"`).
+
+- `unit`: This indicates the unit of measurement for the metric, such as quantities, currency (e.g., `"DAI"`), or percentages.
+
+- `dimensions`: A nested array that provides context for the metric by breaking it down into finer categories or segments, such as `"project"` or `"category"`. Each dimension can contain:
+    - `name`: The identifier or key for the dimension.
+    - `path`: A structured representation of the dimension's hierarchy or location within a dataset.
+    - `label`: A human-readable label for the dimension, which can be used for display purposes.
+    - `description`: A brief explanation of the dimension to give users an understanding of what it represents.
+    - `icon`: A graphical representation or icon associated with the dimension for easier identification in user interfaces.
+
+- `value`: The actual numerical value of the metric for each row within the specified period.
+
+- `sum`: A total or aggregated value of the metric over the entire period, providing a summarized figure.
+
+### A Note about Times
+
+Time is a bit of a sore subject in JavaScript, and we wrestled a bit with how to attack this problem.
+
+First, we started with the builtin `Date` type. Unfortunately, `Date` objects are local-time objects. That means that `new Date('2024-12-25')` might mean one time on this machine and another time on someone elses. While `Date` objects _can_ be created using UTC (`new Date('2024-012-25T14:46:22.001Z')`), the resulting `Date` object is still in local time. While `toISO()` does exist, which will output a UTC timestamp, there is no way to tell whether or not the `Date` _was created_ with a UTC timestamp and actually creating the time object the user thought they were creating. Imagining calling the `Date` constructor and ending up with a time different than the one you thought you passed in. Eek.
+
+We then considered strings, but those suffer from a load of other problems and they are only really going to be runtime checked.
+
+As this is a time-series analytics system, times are rather important to get right, so we thought we'd stick to a data type that has time, date, and timezone information all in one object. Enter the [`luxon`](https://moment.github.io/luxon/#/) library. The luxon library had exactly the data object we were looking for. It is difficult (but not impossible) to create a luxon `DateTime` object with a timezone you weren't intending to use.
+
+This is why our analytics API uses these luxon types as inputs and outputs to the system: to make it hard to screw up.
+
+## Inserting Data
+
+The `IAnalyticsStore` interface is the primary entry point for inserting and deleting data. Multiple storage implementations are provided, but for simplicity we can get up and running quickly with the [`MemoryAnalyticsStore`](#memory).
+
+```typescript
+import { MemoryAnalyticsStore } from "@powerhousedao/analytics-engine-memory";
+
+const store = new MemoryAnalyticsStore();
+```
+
+Data can be added using the `addSeriesValue` method.
+
+```typescript
+import { DateTime } from "luxon";
+import { AnalyticsPath } from "@powerhousedao/analytics-engine-core";
+
+const source = AnalyticsPath.fromString("example/insert");
+await store.addSeriesValue([
+  {
+    start: DateTime.utc(2021, 1, 1),
+    source,
+    value: 10000,
+    unit: "DAI",
+    metric: "budget",
+    dimensions: {
+      budget: AnalyticsPath.fromString("atlas/legacy/core-units/PE-001"),
+      category: AnalyticsPath.fromString(
+        "atlas/headcount/CompensationAndBenefits/FrontEndEngineering"
+      ),
+      project: source,
+    },
+  },
+]);
+```
+
+## Subscribing to Data Changes
+
+The `IAnalyticsStore` also provides an API for subscribing to data changes. This is achieved by subscribing to an `AnalyticsPath`.
+
+```typescript
+const store = new MemoryAnalyticsStore();
+
+// subscribe
+const unsub = store.subscribeToSource(AnalyticsPath.fromString("atlas/"), (source) => {
+  console.log('Atlas data was changed!');
+
+  // decide whether or not to requery
+});
+
+// elided
+
+// remove your subscription
+unsub();
+```
+
+The subscription API provides many of the same guarantees regarding pathing that the rest of the analytics system does.
+
+```typescript
+store.subscribeToSource(AnalyticsPath.fromString("atlas/"), handler);
+
+// this will trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("atlas/foo"), ... });
+
+// this will trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("atlas/foo/bar"), ... });
+
+// this will NOT trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("rwa/foo"), ... });
+```
+
+Wildcards can also be used at sub-levels of the path.
+
+```typescript
+store.subscribeToSource(AnalyticsPath.fromString("atlas/*/test"), handler);
+
+// this will trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("atlas/foo/test"), ... });
+
+// this will trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("atlas/another-thing/test"), ... });
+
+// this will trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("atlas/foo/test/a/b/c"), ... });
+
+// this will NOT trigger the handler
+await store.addSeriesValue({ source: AnalyticsPath.fromString("rwa/foo/test"), ... });
+```
+
+## Store Implementations
+
+Multiple storage implementations are provided, each with comprehensive documentation. See the corresponding docs for:
+
+- [MemoryAnalyticsStore](#memory)
+- [BrowserAnalyticsStore](#browser)
+- [PostgresAnalyticsStore](#postgres)

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/memory.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 1
+---
+
+# Memory Store
+
+The `MemoryAnalyticsStore` is an `IAnalyticsStore` implementation that uses a an in-memory database as its storage mechanism. Under the hood, we load a WASM build of Postgres, called [PGlite](https://pglite.dev/).
+
+<aside class="notice">
+See the <a href="#compatibility">Compatibility</a> section for details on which stores are intended to be used in different execution environments.
+</aside>
+
+## Construction
+
+The `MemoryAnalyticsStore` is simple to create.
+
+> Create with no arguments.
+
+```typescript
+const store = new MemoryAnalyticsStore();
+```
+
+> The `MemoryAnalyticsStore` may also be created with optional contructor arguments that may be helpful for debugging or metrics collection.
+
+```typescript
+const store = new MemoryAnalyticsStore({
+  queryLogger: querydefaultQueryLogger("memory"),
+  resultsLogger: defaultResultsLogger("memory"),
+  profiler: new PassthroughAnalyticsProfiler(),
+});
+```
+
+For more details on these optional constructor parameters, see the [Utilities](#utilities) section.
+
+> Additionally, both `knex` and `pglite` objects may be passed in. This is helpful in contexts where multiple objects are sharing the same database.
+
+```typescript
+// knex must be created with these options
+const knex = knexFactory({ client: "pg", useNullAsDefault: true });
+
+// create your own Pglite instance and pass it in
+// See (https://github.com/electric-sql/pglite/blob/main/packages/pglite/src/interface.ts) for full list of options.
+const pgLiteFactory = () => PGlite.create({
+  debug: 3,
+  relaxedDurability: false,
+});
+
+const store = new MemoryAnalyticsStore({
+  knex,
+  pgLiteFactory,
+})
+```
+
+## Initialization
+
+While easy to use, the `MemoryAnalyticsStore` requires an asynchronous initialization step. This is for two reasons.
+
+In cases where the `MemoryAnalyticsStore` was not provided a `PGlite` instance, it needs time to download and initialize the WASM build.
+
+Additionally, it also needs to initialize the database schema of the in-memory database. This is distinct from the <a href="#postgres">Postgres implementation</a>, which assumes a fully-initialized Postgres database already exists. The initialization is idempotent, so tables already created will not be recreated.
+
+The full SQL query used can be found in the [`MemoryAnalyticsStore` source](https://github.com/powerhouse-inc/analytics-engine/blob/main/browser/src/MemoryAnalyticsStore.ts).
+
+> Note that this method is not available on the `IAnalyticsStore` interface, but only on the `MemoryAnalyticsStore` type.
+
+```typescript
+// create the store
+const store = new MemoryAnalyticsStore();
+
+// initialize it
+await store.init();
+```

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/pg.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 3
+---
+
+# Postgres Store
+
+The `PostgresAnalyticsStore` is an `IAnalyticsStore` implementation that leverages a Postgres database. It requires some APIs that do not run in a browser, and is intended for server-side applications.
+
+<aside class="notice">
+See the <a href="#compatibility">Compatibility</a> section for details on which stores are intended to be used in different execution environments.
+</aside>
+
+## Construction
+
+The `PostgresAnalyticsStore` uses the [`pg`](https://www.npmjs.com/package/pg) package and requires Postgres connection information.
+
+By providing a PG connection string, the store will automatically create a `pg` instance, internally.
+
+A docker-compose file is provided [here](https://github.com/powerhouse-inc/analytics-engine/blob/main/pg/docker-compose.test.yml) that will spin up an instance quickly. Note that it cannot be copy/pasted but must be run in the checked out repository to access the correct initialization scripts. See the [developer documentation](https://github.com/powerhouse-inc/analytics-engine/tree/main?tab=readme-ov-file#pg) for more information.
+
+> Create with only a connection string.
+
+```typescript
+// connects to a local postgres instance, configured by the provided docker-compose file
+const store = new PostgresAnalyticsStore({
+  connectionString: "postgresql://postgres:password@localhost:5555/analytics",
+});
+```
+
+> Instead, create with a `knex` object.
+
+```typescript
+import knexFactory from "knex";
+
+const knex = knexFactory({
+  client: "pg",
+  connection: "...",
+});
+
+const store = new PostgresAnalyticsStore({
+  knex,
+});
+```
+
+> The `PostgresAnalyticsStore` may also be created with optional contructor arguments that may be helpful for debugging or metrics collection.
+
+```typescript
+const store = new PostgresAnalyticsStore({
+  queryLogger: querydefaultQueryLogger("memory"),
+  resultsLogger: defaultResultsLogger("memory"),
+  profiler: new PassthroughAnalyticsProfiler(),
+});
+```
+
+For more details on these optional constructor parameters, see the [Utilities](#utilities) section.
+
+## Raw Queries
+
+Though there is no method on `IAnalyticsStore` for running arbitrary queries, the `PostgresAnalyticsStore` implementation provides a `raw(sql: string)` method. This is used only in development, testing, and [benchmarking](https://github.com/powerhouse-inc/analytics-engine/blob/main/benchmarks/src/wasm.ts) situations and is not intended for production use cases.
+
+```typescript
+const results = store.raw(`select distinct unit from "AnalyticsSeries"`);
+```

package/docs/academy/02-AdvancedTutorial/04-WorkWithData/06-Analytics Engine/typescript/schema.md

@@ -0,0 +1,14 @@
+# Database Schema
+
+![untitled](../images/dbs.png)
+*Database table structures for the analytics engine.*
+
+Analytics information  is stored in three database tables: 
+
+- `AnalyticsSeries`: This table stores the raw data over a period with its metric, value, unit, function and parameters.
+- `AnalyticsDimension`: This table stores all available dimensions for each series.
+- `AnalyticsSeries_AnalyticsDimension`: Many to many lookup table, storing relationships between series and dimensions.
+
+The `browser` package automatically creates this schema in the PGLite instance.
+
+The `postgres` package, on the other hand, [contains an init script](https://github.com/powerhouse-inc/analytics-engine/blob/main/pg/test/scripts/initdb.sh) that can be used to create the correct schema in your database.