diff --git a/learn/_outline-prompt.md b/learn/_outline-prompt.md new file mode 100644 index 00000000..7dce06de --- /dev/null +++ b/learn/_outline-prompt.md @@ -0,0 +1,218 @@ +# Harper Learn Guide Outline Generator Prompt + +Use this prompt to generate detailed outlines for new Learn section guide pages. + +## Your Task + +You are creating a detailed outline for a new Harper Learn guide page. Your outline should: + +1. Follow the Learn guide template structure exactly +2. Match the writing style and prose-like nature of existing Learn guides +3. Build naturally on concepts from previous guides +4. Include detailed notes using comment syntax for content guidance +5. Not be a reference page - this is narrative, educational content + +## Required Context Files to Review + +Before creating the outline, you MUST read these files to understand context: + +1. **`learn/index.mdx`** - Introduction to the Learn section +2. **`learn/getting-started/install-and-connect-harper.mdx`** - First guide, understand writing style +3. **`learn/getting-started/create-your-first-application.mdx`** - Second guide, what concepts are introduced +4. **Any existing `learn/` guides** - Check what content already exists to ensure natural flow +5. **Relevant `docs/` pages** - Source material for technical details (paths will be provided) + +## Learn Section Philosophy (Key Points) + +- **Narrative, prose-like guides** that teach concepts, not just list features +- **Build on previous guides** - always reference what was introduced earlier +- **Three target personas**: AI agents, "Get-it-done" developers, "Inquisitive" developers +- **Example-based and hands-on** - provide concrete, working examples +- **Ordered logically** - guides should be completable in sequence like a course +- **Independently referenceable** - each guide should also work standalone with proper prerequisites +- **End-to-end demonstrations** - fully show features in action, not partial examples +- **Link to reference docs** - guides teach, references provide complete technical details +- **Not promoting deprecated features** - focus on recommended approaches (e.g., avoid Fastify routes, SQL, clustering) + +## Template Structure + +Every Learn guide follows this structure: + +```mdx +--- +title: +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +{/* Introduction paragraph - 2-4 sentences providing a high-level description of what this guide covers and why it matters. Should connect to previous guides when applicable. */} + +## What You Will Learn + +{/* Bulleted list of specific learning outcomes - be concrete and actionable. 4-7 items typically. */} + +## Prerequisites + +{/* List required prior knowledge and tools. Always link to other guides for knowledge prerequisites. Include Harper installation requirements (CLI, local installation, or Fabric instance). May include repo templates or setup steps. */} + +## <Content Section 1> + +{/* AI Generated Outline: Detailed note about what content goes here, examples to include, concepts to explain, etc. */} + +### <Subsection if needed> + +{/* AI Generated Outline: More specific guidance for this subsection */} + +## <Content Section 2> + +{/* AI Generated Outline: ... */} + +## <Final Content Section> + +{/* AI Generated Outline: ... */} + +## Additional Resources + +{/* Links to: +- Related reference documentation pages +- Other relevant Learn guides +- External resources if applicable +- Can duplicate some prerequisite links +Should be the LAST section */} +``` + +## Comment Syntax for Notes + +Use MDX-style comments with the prefix "AI Generated Outline:" for all guidance notes: + +```mdx +{/* AI Generated Outline: This section should explain X concept. Include a code example using Y. Reference the Dog table from Getting Started. Build on the config.yaml knowledge from the Create Your First Application guide. */} +``` + +These comments should: +- Provide clear content guidance for the section +- Suggest specific examples or code snippets to include +- Reference previous guides and what concepts to build on +- Note connections to reference documentation +- Suggest visual aids (diagrams, code blocks, etc.) +- Indicate the appropriate level of detail (overview vs deep-dive) + +## Writing Style Guidelines + +When creating outline notes, guide the writer to: + +1. **Use narrative, teaching-focused prose** - Explain concepts in a conversational, educational tone +2. **Build on previous knowledge explicitly** - "As you saw in Create Your First Application..." or "Remember the Dog table we created earlier..." +3. **Preview upcoming topics naturally** - "We'll explore this in depth in the Custom Resources guide..." +4. **Include concrete examples** - Prefer building on the Dog/first-harper-app example or similar +5. **Use code examples consistently** - Include both `curl` and `fetch` examples for HTTP requests +6. **Support both local and Fabric** - Provide instructions for both when relevant +7. **Teach the "why" not just the "how"** - Explain why something matters, not just what it does + +## Example Comment Patterns + +Good outline comments explain purpose and provide guidance: + +```mdx +## Section Title + +{/* AI Generated Outline: This section deepens the understanding of X introduced in [Previous Guide]. Start with a brief recap of what the user already knows, then explain [new concept]. Include a concrete example that extends the Dog table by adding [feature]. Show both the code and the result. Explain why this pattern is useful for [use case]. Reference the [Y Reference Doc] for complete technical details. */} + +### Subsection Title + +{/* AI Generated Outline: Provide a comparison between X and Y approaches. Use a simple table or bullet points to highlight key differences. Recommend when to use each approach with 2-3 practical scenarios. Keep this at a conceptual level - detailed API information belongs in the reference docs. */} +``` + +## Section Structure Guidance + +Typical Learn guide sections (adapt based on content): + +1. **Conceptual Foundation** - Explain the "what" and "why" of the topic +2. **Basic Implementation** - Simple, working example building on Getting Started +3. **Common Patterns** - Show 2-3 typical use cases +4. **Advanced Concepts** - Deeper features (but save some for future guides) +5. **Best Practices** - Recommendations and gotchas +6. **Debugging/Troubleshooting** - Common issues and solutions +7. **Transitional/Preview** - Set up expectations for next guides +8. **Additional Resources** - Links to references and related content + +Not every guide needs all sections - adapt based on the topic. + +## What to Include in Prerequisites + +Prerequisites should list: + +1. **Previous Learn guides** - Link to specific guides the reader should complete first +2. **Concepts assumed** - "Basic familiarity with X" or "Understanding of Y from previous guide" +3. **Tools required** - "Harper CLI", "Working Harper installation", "Node.js", etc. +4. **Setup requirements** - "Clone this repo template" or "Complete the setup from [guide]" + +Don't list the general prerequisites (Node.js, HTTP client, etc.) unless it's a Getting Started guide - those are stated in the Learn index. + +## What to Include in Additional Resources + +Additional Resources should link to: + +1. **Reference documentation** - Technical details for APIs, configurations, etc. used in the guide +2. **Related Learn guides** - Other guides that expand on related topics +3. **External resources** - Official docs for third-party tools (Next.js, GraphQL, etc.) +4. **Previous guides** - Can duplicate prerequisite links for convenience + +Format as markdown bullet lists with descriptive link text. + +## Content Balance + +Learn guides should: + +- **Teach concepts narratively** - Don't just list features or options +- **Include enough technical detail** to understand and use the feature +- **Link to reference docs** for complete API specifications and all options +- **Use working examples** that readers can follow along with +- **Build progressively** - Simple to more complex within the guide +- **Set up future guides** - Preview what comes next in the learning journey + +## Common Mistakes to Avoid + +1. **Don't create reference pages** - These are guides, not exhaustive documentation +2. **Don't skip connections to previous content** - Always build on what came before +3. **Don't use incomplete examples** - Show working, end-to-end demonstrations +4. **Don't assume knowledge not yet introduced** - Check prerequisites carefully +5. **Don't go too deep too fast** - Save advanced topics for later guides +6. **Don't forget both local and Fabric** - Support both where applicable +7. **Don't omit the "why"** - Explain why something matters, not just how to do it + +## Recommendations for Docs Changes + +After creating the outline, provide recommendations for how existing `docs/` pages should be updated now that this Learn guide will exist: + +- Which sections can be removed (now covered in Learn) +- What should remain as technical reference +- What content might move to future Learn guides +- How to restructure for clarity + +## Input Format + +You will receive: + +1. **Guide topic/title** - What this guide is about +2. **Target section** - Where it fits (Getting Started, Developers, Administration) +3. **Outline notes** - Specific requirements and sections to include +4. **Source material** - Which `docs/` pages to pull information from + +## Output Format + +Provide: + +1. **The complete MDX outline file** - Ready to save with all comment notes +2. **Summary of the outline** - Brief explanation of structure and flow +3. **Recommendations for docs changes** - What to update in existing documentation +4. **Notes on writing style** - Reminders about tone, examples, and connections to make + +--- + +## Now Create the Outline + +Based on the input provided below, create a detailed outline for a new Harper Learn guide following all the guidelines above. + +**Input will be provided by the user in the conversation.** diff --git a/learn/developers/harper-application-and-plugin-development.mdx b/learn/developers/harper-application-and-plugin-development.mdx new file mode 100644 index 00000000..40e5f797 --- /dev/null +++ b/learn/developers/harper-application-and-plugin-development.mdx @@ -0,0 +1,240 @@ +--- +title: Harper Application and Plugin Development +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import HarperArchitectureDiagram from '../../src/components/learn/harper-architecture-diagram.mdx'; + +{/* AI Generated Outline: Introduction paragraph - to be written in prose style explaining that this guide deepens the understanding of Harper Applications beyond the Getting Started section, focusing on the architecture, development patterns, and tooling that developers use day-to-day when building with Harper. */} + +In the Getting Started guides you successfully installed Harper and created your first application. You experienced Harper's schema and database system, and the automatic REST API feature too. This guide dives deeper into Harper's Component Architecture differentiating applications from plugins, and introduces multiple new ways to interact with Harper. By the end of this guide you will be a confident Harper application developer capable of creating just about anything with Harper! + +## What You Will Learn + +- The fundamental concepts and architecture of Harper Applications +- How applications, plugins, and extensions work together in the Harper ecosystem +- The distinction between applications and extensions/plugins, and when to use each +- How to interact with Harper using the Operations API and CLI +- Essential debugging techniques for Harper application development +- Best practices for structuring and developing Harper applications + +## Prerequisites + +- Completed [Install and Connect Harper](../getting-started/install-and-connect-harper) +- Completed [Create Your First Application](../getting-started/create-your-first-application) +- Basic familiarity with Node.js and JavaScript +- Working Harper installation (local or Fabric) + +## Revisiting Harper's Architecture + +{/* AI Generated Outline: Expand on the architecture introduced in Getting Started, providing deeper explanation of the component system. Use the architecture diagram/ASCII art from Getting Started as reference point but explain in more detail how the layers interact. */} + +In the previous guide we introduced a high-level Harper architecture diagram: + +<HarperArchitectureDiagram/> + +And defined some key Harper concepts: + +**Components** are extensions of the core Harper systems, and are further classified as **plugins** and **applications**. + +**Plugins** have access to APIs exposing many of Harper's core services, and are capable of implementing more advanced features than what the core services provide. + +**Applications** use plugins to implement user-facing functionality and business logic, such as implementing database schemas and creating web applications. + +The most important thing to remember is that plugins enable the functionality and applications implement it. Similar to that of a front-end framework. React is like a plugin; on its own it doesn't actually do anything. You actually need to build an application with React for it do anything meaningful. + +Plugins have replaced an old Harper component system called **extensions**. Plugins and extensions have essentially the same definition, but different APIs. In time, extensions will be deprecated, and we encourage all developers to use the plugins immediately. However, both systems are fully supported in Harper v4 and v5. + +### The Harper Stack in Detail + +{/* AI Generated Outline: Detailed prose explanation of each layer: +- Core Services (database, networking, component management) - what they provide, why they matter +- Plugins (built-in vs custom) - their role in extending core functionality +- Applications - the user-facing implementations that tie everything together */} + +Harper itself is a Node.js application. It runs in a single process, and uses worker threads for parallelization. Harper is meant to be a long-running process. Harper instances are meant to be treated as "serverful" systems (contrary to ephemeral "serverless" services). As such, Harper's main thread is meant to always stay running. The concept of a "restart" is specific to restarting the worker threads, and persisting the main thread. Harper uses a rolling restart in order to ensure the Harper system remains functional throughout a restart. Furthermore, the entire Harper process can be safely stopped and started, but generally that should be unnecessary for application development. + +> Harper provides an environment variable, `HARPER_EXIT_ON_RESTART`, that will exit the process when it is instructed to restart. This is meant to be used along side a container environment restart policy such as docker's `--restart=unless-stopped` so that the entire Harper process can be restarted. Its important to keep in mind that full process restarts will disrupt functionality. + +Plugins run exclusively on worker threads, but the older version, extensions, can run on both the main and worker threads. Some of Harper's core services, such as the database and the networking socket router, are implemented directly within the main process. However, a majority of Harper's core functionality is implemented as built-in plugins and extensions. One critical advantage that plugins have over extensions is their ability to respond to configuration changes without restarting. + +Both the `graphqlSchema` database schema system and the `rest` automatic REST API features from the previous guide are technically implemented as built-in extensions still. If you were running Harper locally, the `harper dev` command automatically restarted Harper for you. And if you were using Fabric, this is why you had to click on the "Restart Cluster" button. We are actively migrating all built-in extensions to the plugin API, and once complete, a lot of Harper will run entirely in worker threads and require less restarts in order to respond to configuration and file changes. Aside from the subtle differences in execution context, extensions and plugins very much serve the same purpose. Aside from this section where we are deliberately specifying the technical differences between the two, we have switched to using the plugin terminology entirely. This is to simplify and align our documentation to Harpers ideal future. + +Since core services and plugins are the building blocks of applications, they too can run across all threads. As an application developer, you don't necessarily need to worry to much about what plugins are doing behind the scenes; however, its important to keep in mind that for now, restarting Harper is an important step throughout application development, deployment, and management. Later in this guide you will learn other methods for restarting Harper beyond just the `dev` command. + +### Component Classification: Built-in vs Custom + +{/* AI Generated Outline: Explain the distinction between built-in and custom components, why this matters for development, and how to reference each type. Include practical examples. */} + +Harper further classifies components (plugins and applications) as either built-in or custom. **Built-in** components are internal to Harper, require no additional installation steps, and are immediately accessible for use. The `graphqlSchema` and `rest` plugins are great examples of built-in plugins. **Custom** components are external to Harper, generally available as an npm package or git repository, and do require additional installation steps in order to be used. Custom components can be authored by anyone, including Harper. Any of Harper's official custom components are published using the `@harperdb` and `@harper` package scopes, such as the [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) plugin for developing Next.js applications or the [`@harperdb/status-check`](https://github.com/HarperDB/status-check) application. + +Harper's reference documentation contains detailed documentation for all built-in components. Custom components will be documented within their respective repositories. + +Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just refer to them as "applications". However, there is a multitude of both built-in and custom plugins, and so the documentation tends to specify whenever relevant. + +{/* The AI outline included a sub-section here for component lifecycle. I think we have enough text so far and need to move into some actual development. I think lifecycle will fit in better later too when the user has learned more about managing components, particularly applications using the Operations API and CLI. */} + +{/* I'm not sold on these next four sub-sections. I think they are good titles for the reference page on components. I think the content written above walks the line of informative but not-overly technical well-enough. For more in depth docs, that is where the components/applications/plugins reference page will come into play. Leaving the sections here for now as the rest of the guide is drafted, but will likely move them and rewrite the reference page quite a bit. */} + +{/* ### What Makes Something an Application? */} + +{/* AI Generated Outline: Elaborate on applications as user-facing implementations. Provide concrete examples: +- A Next.js web application serving a UI +- An Apollo GraphQL server providing an API +- A custom REST API using resources.js +Use the mermaid diagram from docs/developers/applications/index.md as visual aid. */} + +{/* ### What Makes Something a Plugin? */} + +{/* AI Generated Outline: Explain extensions as the building blocks that enable functionality. Examples: +- `graphqlSchema` enables table definition (already used in Getting Started) +- `rest` enables automatic REST API generation (already used in Getting Started) +- `@harperdb/nextjs` enables building Next.js apps +- Custom extensions can depend on other extensions */} + +{/* ### When to Build an Application vs an Plugin */} + +{/* AI Generated Outline: Practical guidance on decision-making. Key principle: extensions enable, applications implement. Provide decision tree or clear guidelines. */} + +{/* ### The Plugin API */} + +{/* AI Generated Outline: Briefly mention the v4.6+ plugin system as covered in docs/developers/applications/index.md, note it's experimental, and reference the plugin API docs for readers who want to explore. Don't go too deep since this is fundamentals. */} + +## Working with the Operations API + +{/* AI Generated Outline: Introduce the Operations API as the primary interface for managing Harper programmatically. Build on the /health endpoint from Getting Started. */} + +In the first guide, we introduced you to the `/health` endpoint. This is provided by Harper's built-in Operations API. + +The **Operations API** provides a full set of capabilities for configuring, deploying, administering, and controlling Harper. It is configured on port `9925` by default, and all requests are JSON-based POST requests to the root path (except for the `/health` endpoint of course). + + + + +### Common Operations API Endpoints + +{/* [NOTE: Showcase a few key endpoints beyond /health: +- restart_service (mentioned in docs/developers/applications/index.md) +- read_log (mentioned in docs/developers/applications/debugging.md) +- Other essential operations for application development +Include code examples for 1-2 operations.] */} + +### Operations API vs Application REST APIs + +{/* [NOTE: Clarify the distinction - Operations API (port 9925) for system management vs REST API (port 9926) for application data. This reinforces concepts from Getting Started.] */} + +## Working with the Harper CLI + +{/* [NOTE: Expand on CLI usage beyond the basic `harper` and `harper dev` commands already introduced in Getting Started.] */} + +### Essential CLI Commands for Application Development + +{/* [NOTE: Cover key commands developers use regularly: +- `harper` (already used in Getting Started - installation) +- `harper dev` (already used in Getting Started - development) +- `harper deploy` (briefly mentioned in Getting Started bonus section) +- Commands for component management +Include practical examples and when to use each.] */} + +### CLI vs Operations API: Choosing Your Tools + +{/* [NOTE: Explain when to use CLI (local development, deployments) vs Operations API (programmatic control, automation). They often accomplish the same things via different interfaces.] */} + +## Debugging Harper Applications + +{/* [NOTE: Essential debugging content from docs/developers/applications/debugging.md] */} + +### Development Mode and Debugging + +{/* [NOTE: Explain `harper dev` in more depth: +- Single-threaded mode for easier debugging +- File watching and auto-restart (already experienced in Getting Started) +- How to connect a debugger (Chrome DevTools, VSCode, WebStorm) +Include step-by-step instructions with code/configuration examples.] */} + +### Logging: Console vs Harper Logger + +{/* [NOTE: Explain the distinction: +- console.log() for local development (fine for what was done in Getting Started) +- `logger` global for production use +- Different log levels (trace, debug, info, warn, error, fatal, notify) +Include examples of using the logger in resources.js or other application code.] */} + +### Viewing and Querying Logs + +{/* [NOTE: Explain how to access logs: +- Local file system (~/hdb/log/hdb.log) +- Studio Status page (for Fabric users) +- `read_log` operation from Operations API +Include practical examples.] */} + +### Debugging Strategies and Common Issues + +{/* [NOTE: Practical tips for debugging: +- Setting breakpoints in resources.js +- Debugging schema loading issues +- Troubleshooting plugin configuration +- Common errors and how to resolve them] */} + +## Application Structure Best Practices + +{/* [NOTE: Guidance on organizing Harper applications for maintainability] */} + +### Core Application Files + +{/* [NOTE: Explain the purpose and best practices for: +- config.yaml (introduced in Getting Started) +- schema.graphql (introduced in Getting Started) +- resources.js (will be covered in depth in next guide) +- package.json (for dependencies) +- Directory structure recommendations] */} + +### Configuration Management + +{/* [NOTE: Deeper dive into config.yaml: +- How plugins are configured +- Environment-specific configurations +- Configuration validation and troubleshooting +Build on the simple config.yaml example from Getting Started.] */} + +### File Organization and Conventions + +{/* [NOTE: Recommended patterns for growing applications: +- When to split schemas into multiple files +- Organizing resources by domain +- Directory structures for larger applications] */} + +## Building on the Foundation + +{/* [NOTE: Transitional section that ties everything together and previews what comes next] */} + +### What You've Accomplished + +{/* [NOTE: Recap of the conceptual foundation laid: +- Deep understanding of Harper's architecture +- Knowledge of component types and when to use each +- Familiarity with essential tooling (CLI, Operations API) +- Debugging capabilities +- Best practices for application structure] */} + +### Next Steps in Your Harper Journey + +{/* [NOTE: Preview upcoming Learn guides: +- Deep dive into Custom Resources and JavaScript (resources.js in detail) +- Schema definition and data modeling +- Caching and performance +- Authentication and security +- Web applications and frontends +Each preview should reference concepts introduced in this guide.] */} + +## Additional Resources + +- [Component System Reference](../../reference/components/) - Complete technical reference for components, applications, and extensions +- [Built-In Extensions](../../reference/components/built-in-extensions) - Reference for all built-in Harper extensions +- [Plugin API](../../reference/components/plugins) - Documentation for the experimental plugin system +- [Operations API Reference](../../reference/operations-api/) - Complete Operations API documentation +- [Harper CLI Reference](../../docs/deployments/harper-cli) - Full CLI command reference +- [Harper Configuration](../../deployments/configuration) - Complete configuration options +- [Resource API](../../reference/resources/) - Technical reference for the Resource interface (preview for next guide) diff --git a/learn/getting-started/create-your-first-application.mdx b/learn/getting-started/create-your-first-application.mdx index e6e6099f..10bbc058 100644 --- a/learn/getting-started/create-your-first-application.mdx +++ b/learn/getting-started/create-your-first-application.mdx @@ -4,6 +4,7 @@ title: Create Your First Application import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import HarperArchitectureDiagram from '../../src/components/learn/harper-architecture-diagram.mdx'; With Harper successfully installed and setup, let's dive into building your first Harper Application, a simple REST API. Harper lets you build powerful APIs with minimal effort. @@ -24,22 +25,7 @@ With Harper successfully installed and setup, let's dive into building your firs Before diving into building your first Harper application, it is important to understand a bit about Harper's architecture. The simplest way to think about Harper is as a stack. -``` -┏━━━━━━━━━━━━━━━━━━┓ -┃ Applications ┃ -┠──────────────────┨ -┃ Plugins ┃ -┃ - rest ┃ -┃ - graphqlSchema ┃ -┃ - ... ┃ -┠──────────────────┨ -┃ Core Services: ┃ -┃ - database ┃ -┃ - networking ┃ -┃ - component ┃ -┃ management ┃ -┗━━━━━━━━━━━━━━━━━━┛ -``` +<HarperArchitectureDiagram/> At the bottom are the **core services** that make up the foundation of the Harper platform. This includes the high-performance **database**, extensible **networking** middleware, and **component** management system. Components are extensions of the core Harper system, and are further classified as **plugins** and **applications**. diff --git a/src/components/learn/harper-architecture-diagram.mdx b/src/components/learn/harper-architecture-diagram.mdx new file mode 100644 index 00000000..919f8b39 --- /dev/null +++ b/src/components/learn/harper-architecture-diagram.mdx @@ -0,0 +1,16 @@ +``` +┏━━━━━━━━━━━━━━━━━━┓ +┃ Applications ┃ +┠──────────────────┨ +┃ Plugins ┃ +┃ - rest ┃ +┃ - graphqlSchema ┃ +┃ - ... ┃ +┠──────────────────┨ +┃ Core Services: ┃ +┃ - database ┃ +┃ - networking ┃ +┃ - component ┃ +┃ management ┃ +┗━━━━━━━━━━━━━━━━━━┛ +``` \ No newline at end of file diff --git a/src/components/learn/installation-tabs.tsx b/src/components/learn/installation-tabs.tsx new file mode 100644 index 00000000..b3245672 --- /dev/null +++ b/src/components/learn/installation-tabs.tsx @@ -0,0 +1,21 @@ +import React, { ReactNode } from 'react'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const InstallationGroup = ({ children }: { children: ReactNode }) => ( + <Tabs groupId="installation"> + {children} + </Tabs> +); + +export const Local = ({ children }: { children: ReactNode }) => ( + <TabItem value="local" label="Local Installation"> + {children} + </TabItem> +); + +export const Fabric = ({ children }: { children: ReactNode }) => ( + <TabItem value="fabric" label="Fabric"> + {children} + </TabItem> +);