docs: DOC-610: A mental model of servers & clients#7169
docs: DOC-610: A mental model of servers & clients#7169jjbrosnan wants to merge 6 commits intodeephaven:mainfrom
Conversation
jjbrosnan
added
documentation
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation about Deephaven's server-client architecture, providing a mental model to help users understand when to use server-side vs client-side APIs. The documentation includes technical implementation details, performance considerations, and security aspects.
Key changes:
- Creates a new conceptual guide explaining servers and clients with restaurant analogy
- Documents Deephaven's technical architecture using gRPC and Arrow Flight
- Provides recommendations for choosing between server-side and client-side APIs
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/python/sidebar.json | Adds navigation entry for the new server-client model documentation |
| docs/python/conceptual/server-client-model.md | Creates comprehensive guide covering server-client concepts, technical implementation, and usage recommendations |
| docs/groovy/sidebar.json | Adds navigation entry for the new server-client model documentation |
| docs/groovy/conceptual/server-client-model.md | Empty file (appears to be a placeholder for shared content) |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
elijahpetty
left a comment
elijahpetty
left a comment
There was a problem hiding this comment.
LGTM structure-wise, I only have a consistency nitpick about periods on bullet point lines
kosak
left a comment
kosak
left a comment
There was a problem hiding this comment.
I have left some pretty opinionated comments.
| @@ -0,0 +1,217 @@ | |||
| --- | |||
| title: Servers & Clients | |||
| --- | |||
There was a problem hiding this comment.
Does this identical file (server-client-model.md) appear in two different places in the doc tree? (Here, and under python/conceptual). I think this might be a mistake in terms of maintainability and organization. Would we rather have some kind of pointer from (both groovy and python) to (some third place for conceptual docs)?
There was a problem hiding this comment.
As of now, everything is completely duplicated for the Groovy docs and the Python docs, though for concept guides there are not many differences.
|
|
||
| ## An example server-client application | ||
|
|
||
| Consider an at-home golf simulator with a launch monitor that captures data about each golf shot. Here's how a Deephaven server-client architecture could enhance this setup: |
There was a problem hiding this comment.
In my opinion, this section should be rewritten to target an example our reader might be familiar with. Deephaven is a high-performance streaming platform for finance professionals. In my opinion it's jarring to ask people to imagine using it for your golf simulator.
| - **Network isolation**: Whether servers should be isolated on separate networks. | ||
| - **Audit logging**: How user actions will be tracked and monitored. | ||
|
|
||
| Deephaven provides different authentication mechanisms that can be configured according to your security requirements. |
There was a problem hiding this comment.
This sentence feels strange because above the reader is provided five aspects that require careful thought (namely authentication, authorization, data encryption, network isolation, and audit logging) but then go on to say that Deephaven provides different authentication mechanisms. (So Deephaven addresses only one of the five points?)
| ### Server-side | ||
|
|
||
| - [Python](https://deephaven.io/core/pydoc/) | ||
| - [Groovy](https://deephaven.io/core/javadoc/) |
There was a problem hiding this comment.
Not your fault but is this our only docs link for Groovy? It drops right into a package index which is overwhelming and kind of useless.
| 4. **User access patterns**: How many users need access? From what types of devices? | ||
| 5. **Scalability needs**: How will your application grow over time? | ||
|
|
||
| Start with the simplest architecture that meets your needs, then scale as required. Many applications begin with a single server and add clients or additional servers as they mature. |
There was a problem hiding this comment.
In my opinion these are fine questions but I don't think we are doing much to help customers answer them.
As a hypothetical, let's say I knew exact answers to 1-5 above. What would I do with this information? How would this help me know how many servers to allocate to Deephaven and how big they should be?
There is no SME reviewer listed on the Jira ticket. There should probably be one.
Still, I want to self-review this from the preview and have Margaret/Elijah look first to make sure the structure is good.
I will add SME reviewer(s) when we decide who they should be.