Conversation
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
There was a problem hiding this comment.
There needs to be links on this page to the documentation for our other config options. We want those searching for more specific installation instructions to easily find their way to our configuration information too.
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
kriszyp
left a comment
kriszyp
left a comment
There was a problem hiding this comment.
This looks a good direction, the "foundations" section looks like it could be really helpful.
docs/foundations/core-concepts.md
Outdated
| 💡 **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place. | ||
| ::: | ||
|
|
||
| ## Extensions (a type of Component) |
There was a problem hiding this comment.
Extensions and Plugins are not different types of components, they are the same type of component: a component designed to be used by other components/apps, not standalone. Plugin is just the new name for this type of component and the name for the new API for configuring this type of component and interacting with the dependent application. Really, the examples listed below are plugins as well (that use the old extension API).
| At a high level: | ||
|
|
||
| - **Core services** handle data, networking, and files. | ||
| - **Extensions** layer in reusable features (REST, GraphQL, Next.js, etc.). |
|
|
||
| - **Database** → Fast storage, queries, and transactions. | ||
| - **Networking** → REST/HTTP, WebSockets, MQTT, and cluster communication. | ||
| - **File system** → File operations and serving static assets. |
There was a problem hiding this comment.
Harper does not ship with a file system. An operating system ships with a file system, along with thousands of other primitives. But we aren't defining an OS here and "file system" is not a meaningful part of Harper. A more important essential service is our component management system.
There was a problem hiding this comment.
I added more comments to the discussion around the diagram as that is where these came from. In short, I used these terms not for their technical accuracy but for there general purposeness for first-time readers.
| - 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. |
|
|
||
| Extensions are Harper’s plug-in modules. They add reusable features to applications and can depend on each other. | ||
|
|
||
| Here are a few common examples: |
There was a problem hiding this comment.
Is this a little redundant with the coverage of plugins in core concepts? Would it be more helpful to describe the architecture of the root configuration of components and the transitive configuration and dependency of components?
There was a problem hiding this comment.
Someday I would like to move the getting started guide outside the versioned docs, but that is beyond the scope of this PR.
kriszyp
left a comment
kriszyp
left a comment
There was a problem hiding this comment.
A couple comments, but this is looking great!
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
Okay, I've kept all my feedback to the docs/ files and I assume we'll copy those to the versions later.
In general this is making great progress. Almost there. I wasn't sure at first we wanted to use "plugins" so prominently, and I'm totally happy with that change. Lets make sure we are consistent then.
| ✅ Quick check: open http://localhost:9925 or run: | ||
|
|
||
| ```bash | ||
| curl http://localhost:9925/health | ||
| ``` |
There was a problem hiding this comment.
Like what happens if the user had selected prod? Would these still work or do they need to try https instead?
There was a problem hiding this comment.
Do they need to try https?
There was a problem hiding this comment.
That is my point; these installation instructions are missing the nuance of the actual user experience of setting up Harper. If the user selected prod defaults during installation then yes they would need to use https. But these docs do not explain that.
There was a problem hiding this comment.
I have a comment further up that mentions this and how we should go about fixing this section
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
Almost there. Please remember to keep changes to the files within docs/ as those are the only ones I'm paying attention too right now. As soon as we are satisfied with those pages, you can copy them over to the versioned_docs/* paths.
docs/foundations/core-concepts.md
Outdated
|
|
||
| Examples you’ll see in the ecosystem include: | ||
|
|
||
| - **Built in extensions**: 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. |
There was a problem hiding this comment.
Should we use "plugins" here and below?
Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
Okay I'm satisfied with this now. I didn't look too closely but I assume the version directories match the docs/ one.
3 participants
The goal of this pull request is to restructure the developer onboarding on Harper, so that they go from zero to first Harper app very quickly.
As a result, I've removed other docs pages that don't accelerate onboarding (but contribute to Harper knowledge) into a different section called "Foundations of Harper"
I also added a Harper architecture page and replaced the diagram.