Initial Documentation Content (#346)

This is the first pile of the documentation content.

- Anything not for this PR is tagged with "Coming soon"
- Lots of design to come
- Currently pulls in the swagger via
https://www.npmjs.com/package/openapi-to-md (could be changed and
improved in the future)

# Testing

```
cd docs
mdbook serve
open http://localhost:3000
```

Closes Docs issues:
- Closes #205
- Closes #204
- Closes #210

Closes embed issues:
- Closes #225
- Closes #226
- Closes #227
- Closes #228

---------

Co-authored-by: Patrick <[email protected]>
Co-authored-by: Matthew Orris <[email protected]>

Author: 3 people

.gitignore

@@ -1,5 +1,7 @@
 docs/book
 
+*drawio.bkp
+
 # Logs
 logs
 *.log

README.md

@@ -22,7 +22,7 @@
 
 # 📖 Gateway Services <a name="about-project"></a>
 
-Gateway is a collection of services that helps make interacting with Frequency easy as working with any web2 API!
+Gateway is a collection of services that helps make interacting with Frequency as easy as working with any web2 API!
 
 <!-- Mermaid Arch maps -->
 
@@ -40,7 +40,6 @@ flowchart LR;
         GS[Graph Service]
         CPS[Content Publishing Service]
         CWS[Content Watcher Service]
-        RS[Graph Reconnection Service]
     end
     S --> AS
     S --> GS
@@ -61,7 +60,7 @@ flowchart LR;
 
 ## 🛠 Built With
 
-Each Gateway services is an independent microservice.
+Each Gateway service is an independent microservice.
 
 ### Tech Stack
 
@@ -97,14 +96,6 @@ Each Gateway services is an independent microservice.
 
 </details>
 
-<details>
-<summary>Reconnection Service</summary>
-
-- [API Documentation](https://projectlibertylabs.github.io/reconnection-service/)
-- [GitHub](https://github.com/ProjectLibertyLabs/reconnection-service)
-
-</details>
-
 <!-- LIVE Docs -->
 
 ## 🚀 Live Docs

docs/book.toml

@@ -4,3 +4,17 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Gateway"
+
+[preprocessor.local]
+command = "node preprocessor.mjs"
+
+
+[output.html]
+no-section-label = true
+git-repository-url = "https://github.com/ProjectLibertyLabs/gateway"
+edit-url-template = "https://github.com/ProjectLibertyLabs/gateway/blob/main/docs/src/{path}"
+preferred-dark-theme = "coal"
+additional-css = ["css/extended.css"]
+
+[output.html.fold]
+enable = true

docs/css/extended.css

@@ -0,0 +1,60 @@
+/* Button Links */
+.button-links {
+  display: flex;
+  justify-content: space-around;
+  align-content: center;
+  align-items: stretch;
+  flex-wrap: wrap;
+}
+
+.button-links a,
+.button-links a:link {
+  box-sizing: content-box;
+  font-weight: 300;
+  color: var(--sidebar-fg);
+  background-color: var(--sidebar-bg);
+  border: 2px solid transparent;
+  border-radius: 15px;
+  user-select: none;
+  padding: 20px 10%;
+  margin: 10px;
+  display: flex;
+  font-size: 2rem;
+  font-weight: 400;
+  flex: 0.5;
+  transition-property: border, color;
+  transition-duration: 0.5s;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+  white-space: nowrap;
+}
+
+@media screen and (max-width: 1080px) {
+  .button-links a,
+  .button-links a:link {
+    box-sizing: border-box;
+    margin: 10px 6px;
+    flex: 0 0 90%;
+    width: 100%;
+    white-space: normal;
+  }
+}
+
+@media screen and (max-width: 400px) {
+  .button-links a,
+  .button-links a:link {
+    box-sizing: border-box;
+    margin: 10px 6px;
+    flex: 0 0 100%;
+    width: 100%;
+    white-space: normal;
+  }
+}
+
+.button-links a:hover,
+.button-links a:visited:hover {
+  text-decoration: none;
+  border: 2px solid var(--sidebar-active);
+  color: var(--sidebar-fg);
+}

docs/preprocessor.mjs

@@ -0,0 +1,121 @@
+// Debugging Help
+// Use console.error, not console.log
+//
+// This does a few things:
+// - Runs openapi-to-md when `{{#swagger-embed ../services/account/swagger.json}}` or other is found
+// - Replaces `{{#button-links}}` with the child links of that page in button form
+// - Replaces `{{#markdown-embed ../services/account/ENVIRONMENT.md [trim from top]}}` or other is found with the contents of that file
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+function runNpxCommand(script, args) {
+  try {
+    const command = `npx -y ${script} -- ${args.map((x) => `"${x}"`).join(' ')}`;
+    const output = execSync(command, { encoding: 'utf-8' });
+    return output;
+  } catch (error) {
+    throw new Error(`Error executing npx command: ${error}`);
+  }
+}
+
+function makeButtonLink({ Chapter }, parentPath) {
+  // Remove any part of the path that the parent already has.
+  // This assumes that there are no nested duplicate names
+  const path = Chapter.path.split('/').filter((x) => !parentPath.has(x));
+  return `<a href="${path.join('/').replace('.md', '.html')}">${Chapter.name}</a>`;
+}
+
+function generateButtonLinks(parent) {
+  // Remove the last /page.md as there might be collisions with that part
+  const parentPath = new Set(parent.path.replace(/\/[^\/]*$/, '').split('/'));
+  return (
+    '<div class="button-links">' + parent.sub_items.map((x) => makeButtonLink(x, parentPath)).join('\n') + '</div>'
+  );
+}
+function replaceButtonLinks(chapter) {
+  if (chapter.sub_items && chapter.content.includes('{{#button-links}}')) {
+    chapter.content = chapter.content.replace('{{#button-links}}', generateButtonLinks(chapter));
+  }
+
+  if (chapter.sub_items) {
+    chapter.sub_items.forEach((section) => {
+      section.Chapter && replaceButtonLinks(section.Chapter);
+    });
+  }
+}
+
+function swaggerEmbed(chapter) {
+  const regex = /{{#swagger-embed\s(.+?)}}/;
+  const match = chapter.content.match(regex);
+  if (match) {
+    const swaggerFile = match[1];
+    const output = runNpxCommand('openapi-to-md', [swaggerFile]);
+    const replaceWith = output.split('\n').slice(5).join('\n');
+    chapter.content = chapter.content.replace(match[0], replaceWith);
+  }
+  if (chapter.sub_items) {
+    chapter.sub_items.forEach((section) => {
+      section.Chapter && swaggerEmbed(section.Chapter);
+    });
+  }
+}
+
+function markdownEmbed(chapter) {
+  const regex = /{{#markdown-embed\s(.+?)\s(.+?)}}/;
+  const match = chapter.content.match(regex);
+  if (match) {
+    const markdownFile = match[1];
+    const output = readFileSync(markdownFile, 'utf8');
+    const replaceWith = output.split('\n').slice(match[2]).join('\n');
+    chapter.content = chapter.content.replace(match[0], replaceWith);
+  }
+  if (chapter.sub_items) {
+    chapter.sub_items.forEach((section) => {
+      section.Chapter && markdownEmbed(section.Chapter);
+    });
+  }
+}
+
+// Function to perform the preprocessing
+function preprocessMdBook([_context, book]) {
+  // Button Links
+  book.sections.forEach((section) => {
+    section.Chapter && replaceButtonLinks(section.Chapter);
+  });
+
+  // Swagger Embed
+  book.sections.forEach((section) => {
+    section.Chapter && swaggerEmbed(section.Chapter);
+  });
+
+  // Markdown Embed
+  book.sections.forEach((section) => {
+    section.Chapter && markdownEmbed(section.Chapter);
+  });
+
+  // Output the processed content in mdbook preprocessor format
+  process.stdout.write(JSON.stringify(book));
+}
+
+if (process.argv < 3) {
+  throw new Error('Something strange is happening');
+}
+
+if (process.argv[2] === 'supports') {
+  process.exit(0);
+}
+
+process.stdin.setEncoding('utf-8');
+process.stdout.setEncoding('utf-8');
+
+// Read data from stdin
+let inputData = '';
+
+process.stdin.on('data', (chunk) => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  preprocessMdBook(JSON.parse(inputData));
+});

docs/src/API/README.md

@@ -0,0 +1,19 @@
+# Account Service
+
+The Account Service provides functionalities related to user accounts on the Frequency network.
+It includes endpoints for managing user authentication, account details, delegation, keys, and handles.
+
+## API Reference
+
+[Open Direct API Reference Page](https://projectlibertylabs.github.io/gateway/account)
+{{#swagger-embed ../services/account/swagger.json}}
+
+## Configuration
+
+{{#markdown-embed ../services/account/ENVIRONMENT.md 2}}
+
+## Best Practices
+
+- **Secure Authentication**: Always use secure methods (e.g., JWT tokens) for authentication to protect user data.
+- **Validate Inputs**: Ensure all input data is validated to prevent injection attacks and other vulnerabilities.
+- **Rate Limiting**: Implement rate limiting to protect the service from abuse and ensure fair usage.

docs/src/BestPractices/Performance.md

@@ -0,0 +1,17 @@
+# Content Publishing Service
+
+The Content Publishing Service allows users to create, post, and manage content on the Frequency network. It supports various content types such as text, images, and videos.
+
+## API Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-publishing)
+{{#swagger-embed ../services/content-publishing/swagger.json}}
+
+## Configuration
+
+{{#markdown-embed ../services/content-publishing/ENVIRONMENT.md 2}}
+
+## Best Practices
+
+- **Metadata Management**: Always ensure metadata is correctly associated with content to maintain data integrity.
+- **Content Validation**: Validate content to prevent the submission of inappropriate or harmful material.

docs/src/BestPractices/Security.md

@@ -0,0 +1,19 @@
+# Content Watcher Service
+
+The Content Watcher Service monitors and retrieves the latest feed state, including content updates, reactions, and other user interactions on the Frequency network. It ensures that applications can stay up-to-date with the latest content and user activity.
+
+## API Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-watcher)
+{{#swagger-embed ../services/content-watcher/swagger.json}}
+
+
+## Configuration
+
+{{#markdown-embed ../services/content-watcher/ENVIRONMENT.md 2}}
+
+## Best Practices
+
+- **Efficient Polling**: Implement efficient polling mechanisms to minimize load on the service.
+- **Webhook Security**: Secure webhooks by verifying the source of incoming requests.
+- **Rate Limiting**: Apply rate limiting to prevent abuse and ensure fair usage of the service.

docs/src/Build/AccountService.md

@@ -0,0 +1,20 @@
+# Graph Service
+
+The Graph Service manages the social graphs, including follow/unfollow actions, blocking users, and other social interactions. It allows applications to maintain and query the social connections between users on the Frequency network.
+
+## API Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/graph)
+{{#swagger-embed ../services/graph/swagger.json}}
+
+
+## Configuration
+
+{{#markdown-embed ../services/graph/ENVIRONMENT.md 2}}
+
+
+## Best Practices
+
+- **Data Integrity**: Ensure the integrity of social graph data by implementing robust validation checks.
+- **Efficient Queries**: Optimize queries to handle large social graphs efficiently.
+- **User Privacy**: Protect user privacy by ensuring that graph data is only accessible to authorized entities.

docs/src/Build/ContentPublishing.md

@@ -0,0 +1,49 @@
+# Services
+
+<div class="button-links">
+  <a href="./AccountService.html">Account Service</a>
+  <a href="./ContentPublisher.html">Content PublisherService</a>
+  <a href="./GraphService.html">Graph Service</a>
+  <a href="./ContentWatcher.html">Content WatcherService</a>
+</div>
+
+![Gateway Application Microservice Diagram](../gateway_arch-TopLevelServices.drawio.png)
+
+## Account Service
+
+Account Service is a service enabling easy interaction with accounts on Frequency.
+Accounts are be defined as an `msaId` (a 64 bit identifier) and can contain additional information such as a handle, keys, and more.
+
+- Account creation using [SIWF](https://github.com/ProjectLibertyLabs/siwf)
+- Delegation management
+- User Handle creation and retrieval
+- User key retrieval and management
+
+## Graph Service
+
+The Graph Service is a service enabling easy interaction with graphs on Frequency.
+Each Graph connection on Frequency can be private or public and can be unidirectional (a follow) or bidiectional (double opt-in friend connection).
+
+- Fetch user graph
+- Update delegated user graphs
+- Watch graphs for external updates
+
+## Content Publishing Service
+
+The Content Publishing Service is a service enabling the creation of new content related activity on Frequency.
+
+- Create posts to be broadcast publicly
+- Create replies to posts
+- Create reactions to posts
+- Create updates to existing content
+- Request deletion of content
+- Asset creation with [IPFS](https://ipfs.tech)
+
+## Content Watcher Service
+
+The Content Watcher Service is a service enabling processing external content from Frequency.
+Feed content through your custom webhooks to connect to the larger ecosystem of content.
+
+- Parses and validates Frequency content
+- Filterable webhooks
+- Scanning control