Restructure developer onboarding

docs/developers/applications/index.md

@@ -81,7 +81,7 @@ This guide is going to walk you through building a basic Harper application usin
 
 ## Custom Functionality with JavaScript
 
-[The getting started guide](../../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class.
+[The getting started guide](../../getting-started/quickstart) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class.
 
 To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it:
 

docs/foundations/core-concepts.md

@@ -0,0 +1,80 @@
+---
+title: Core Concepts
+---
+
+# Core Concepts
+
+Before you build your first app with Harper, it helps to understand a few key ideas. These concepts show you how Harper is structured and why it’s flexible enough to power everything from a quick proof-of-concept to a production-ready platform.
+
+## Components
+
+**Components** are the building blocks of Harper.  
+They’re JavaScript-based modules that extend Harper’s core, and they can talk directly to Harper’s [Global APIs](../reference/globals) (databases, tables, resources).
+
+Because components can build on top of each other, they give you composability. For example, both [Applications](../developers/applications/) and [Plugins](../reference/components/plugins) are just kinds of components:
+
+- **Plugins** add individual capabilities, like defining tables or serving static assets.
+- **Applications** pull multiple plugins and resources together into a complete product.
+
+:::info
+💡 **Why it matters:** Instead of wiring up a backend from scratch, you can piece together pre-built functionality and get to working endpoints fast.  
+:::
+
+## Applications (a type of Component)
+
+An **application** is a special kind of component that pulls everything together.  
+Applications rely on plugins to do the work:
+
+- Use `graphqlSchema` to define your data tables.
+- Add `rest` to query that data instantly.
+- Plug in `static` to serve files or front-end assets.
+
+You can even run full frameworks like [Next.js](https://github.com/HarperDB/nextjs) or [Apollo](https://github.com/HarperDB/apollo) as Harper applications.
+
+:::info
+💡 **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place.
+:::
+
+## Plugins
+
+**Plugins** are a special kind of component that are not meant to run standalone, but instead add features to applications or other components. These were originally called **extensions** (and the [extension API](../reference/components/extensions) is still supported), but the new [plugin API](../reference/components/plugins) is simultaneously a simplification and extensibility upgrade.
+
+Examples you’ll see in the ecosystem include:
+
+- **Built in plugins**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) for database and table definitions, [rest](../reference/components/built-in-extensions#rest) for RESTful access to your data, and [static](../reference/components/built-in-extensions#static) for serving files or frontend assets.
+
+- **Custom plugins**: These live outside of Harper and are installed from GitHub or npm. Harper supports a few official ones, and the ecosystem may include community plugins as well. Examples include [@harperdb/nextjs](https://github.com/HarperDB/nextjs) for Next.js integration and [@harperdb/apollo](https://github.com/HarperDB/apollo) for Apollo GraphQL.
+
+:::info
+💡 **Why it matters:** Plugins give Harper its flexibility. You can compose them into applications to get powerful functionality without writing boilerplate yourself.
+:::
+
+## Resources
+
+**Resources** are Harper’s data layer and are implemented using the [`Resource`](../reference/resources/) class.  
+They represent databases, tables, and other data entities, and they provide a unified API for accessing, querying, modifying, and monitoring records.
+
+At the simplest level, resources let you:
+
+- Define schemas and tables for your application data.
+- Query and update that data through Harper’s APIs.
+- Extend the base `Resource` class with JavaScript to define custom data sources or behaviors.
+
+Each `Resource` instance can represent a single record or a collection of records at a given point in time.  
+Static methods on the `Resource` class handle common operations like parsing paths, running transactions, and enforcing access controls, while instance methods give you a transactional view of individual records.
+
+:::info
+💡 **Why it matters:** Whether you’re working with standard tables or custom-defined resources, everything in Harper’s data layer builds on the same model. This gives you consistency when modeling data and flexibility to extend it with your own logic. For full details, see the [Resource reference documentation](../reference/resources/).
+:::
+
+## Server
+
+At the edge of Harper is the **server layer**, which connects your data to the outside world. Harper supports REST/HTTP, WebSockets, MQTT, and more. A single resource can be available through multiple protocols at once—so the same table can power a real-time dashboard, a mobile app, and a backend API.
+
+:::info
+💡 **Why it matters:** You don’t have to choose between protocols. One data model, many ways to access it.
+:::
+
+---
+
+✅ With these concepts in mind, you’re ready to [build your first application](../getting-started/quickstart). That’s where you’ll see how Components, Resources, and Plugins come together in practice.

docs/foundations/harper-architecture.md

@@ -0,0 +1,101 @@
+---
+title: Harper Architecture
+---
+
+# Harper Architecture
+
+Before diving deep into APIs and configuration, it helps to understand the big picture of how Harper works.  
+Harper uses a **three-layer architecture** designed for distributed, edge-first computing. Each layer builds on the next, letting you start simple and scale as your app grows.
+
+![](/img/v4.6/harper-architecture.png)
+
+At a high level:
+
+- **Core services** handle data, networking, and files.
+- **Plugins** layer in reusable features (REST, GraphQL, Next.js, etc.).
+- **Applications** bring everything together to deliver user-facing functionality.
+
+:::info
+💡 **Why it matters:** You focus on building your app, while Harper takes care of scaling, networking, and consistency behind the scenes.
+:::
+
+---
+
+## Core Services
+
+Harper ships with three essential services:
+
+- **Database** → Fast storage, queries, and transactions.
+- **Networking** → REST/HTTP, WebSockets, MQTT, and cluster communication.
+- **Component Management** → The system that loads, configures, and connects components (applications, plugins, resources) so they work together consistently.
+
+Think of these as Harper’s foundation—every extension and app builds on them.
+
+---
+
+## Applications & Extensions
+
+Most of your work will happen here.
+
+### Applications
+
+Applications sit at the top layer. They’re where you implement user-facing features. Examples:
+
+- A **Next.js app** served directly from Harper.
+- A **basic app** from the [Getting Started guide](../getting-started/quickstart) that defines a schema, adds a table, and automatically exposes REST endpoints with the `rest` extension.
+
+Applications don’t re-invent core logic—they declare the plugins they need.
+
+### Component Configuration
+
+Every Harper project starts with a **root configuration**.  
+This configuration declares which components (applications, plugins/extensions, resources) should be loaded and how they should be initialized.
+
+Some components are self-contained, while others include configuration that ties into additional components. For example:
+
+- An application in the root config might load the `rest` plugin.
+- The `rest` plugin exposes data from the database, so its configuration links to `graphqlSchema`.
+- `graphqlSchema` defines the tables that the database service makes available.
+
+This layering of configuration is what makes Harper composable: by declaring one component in your root config, you can enable entire sets of functionality.
+
+:::info
+💡 **Why it matters:** Instead of wiring everything manually, you declare the root config, and Harper initializes the components in the right relationships.  
+:::
+
+---
+
+## Resource API
+
+At the heart of Harper is the **Resource API**. It gives you a unified, consistent way to interact with data.
+
+- `get()` → fetch data
+- `post()` → create data or trigger actions
+- `put()` → replace existing data
+- `patch()` → update part of a record
+
+Every call is wrapped in a transaction, so multi-table operations stay consistent without extra boilerplate.
+
+For the complete API, see the [Resource reference](../reference/resources).
+
+:::info
+💡 **Why it matters:** You can build reliable features—like signups, payments, or analytics—without hand-rolling transaction logic.
+:::
+
+---
+
+## Transaction Model
+
+All requests run inside automatic transactions:
+
+- Read/write across multiple tables in a single request.
+- Automatic change tracking.
+- Guaranteed consistency at commit.
+
+:::info
+💡 **Why it matters:** You don’t have to think about database race conditions or half-finished writes—Harper guarantees integrity by default.
+:::
+
+---
+
+✅ With this architecture in mind, you can see how Harper scales from “hello world” to complex, distributed applications. Next, try putting it into practice by [building your first app](../developers/applications/).

docs/foundations/use-cases.md

@@ -0,0 +1,80 @@
+---
+title: Harper Use Cases
+---
+
+# Harper Use Cases
+
+Harper is designed to cut out infrastructure complexity so you can move faster.  
+Here are some common ways developers use Harper in production today — each one showing how Harper’s architecture translates into real-world outcomes.
+
+---
+
+## RESTful APIs for Distributed & Cached Data
+
+**Great for:** web apps, mobile apps, data-heavy platforms.
+
+Harper’s most common use case is exposing distributed, cached data over a RESTful interface.  
+This lets you serve complex or large-scale datasets efficiently, with built-in caching and global distribution.
+
+- Define your schema with the `graphqlSchema` plugin.
+- Expose it instantly over REST using the `rest` plugin.
+- Take advantage of Harper’s caching layer to serve hot data without extra infrastructure.
+- Power both web and mobile applications from the same API.
+
+:::info
+💡 **Why it matters:** Instead of bolting a cache or API layer onto a database, Harper gives you a unified system that scales for real-world apps.
+:::
+
+---
+
+## Online Catalogs & Content Delivery
+
+**Great for:** e-commerce sites, real estate listings, media & content platforms.
+
+Harper’s distributed architecture makes your pages load fast worldwide, improving **SEO** and **conversion rates**.
+
+- Host your frontend directly with the [Next.js Extension](https://github.com/HarperDB/nextjs).
+- Support any framework using Harper’s extension system.
+- Use Harper’s built-in caching + JavaScript layer to [server-side render pages](https://www.harpersystems.dev/development/tutorials/server-side-rendering-with-multi-tier-cache).
+- Keep pages instantly fresh with built-in [WebSocket connections](../developers/real-time#websockets).
+
+:::info
+💡 **Why it matters:** Instead of stitching together CDN + DB + API layers, you deliver catalog and content experiences from a single platform.
+:::
+
+---
+
+## Data Delivery Networks
+
+**Great for:** live sports updates, flight tracking, software updates.
+
+Harper combines **messaging**, **data storage**, and **application logic** in one system. That means:
+
+- Push real-time updates directly to clients.
+- Process and store data without leaving Harper.
+- Eliminate extra message brokers or caching systems.
+
+Explore the [real-time docs](../developers/real-time) to see how it works.
+
+:::info
+💡 **Why it matters:** You can build real-time data services in hours, not weeks, with fewer moving parts to manage.
+:::
+
+---
+
+## Edge Inference Systems
+
+**Great for:** IoT pipelines, sensor networks, edge AI.
+
+Normally, capturing and analyzing streams at the edge requires a patchwork of tools. Harper simplifies this with:
+
+- **Self-healing connections** that keep data flowing even in flaky environments.
+- The same Harper runtime running at both layers.
+
+:::info
+💡 **Why it matters:** One consistent stack across edge and cloud makes AI/ML inference faster, cheaper, and easier to scale.
+:::
+
+---
+
+✅ Want to explore more? [Contact us](https://www.harpersystems.dev/contact) and we’ll walk you through building your own use case.