Add first batch of GraphQL focused documentation

app/views/pages/developer-guide/graphql/graphql-get-started.liquid

@@ -0,0 +1,101 @@
+---
+converter: markdown
+metadata:
+  title: GraphQL in platformOS
+  description: This guide covers how to use GraphQL in platformOS
+---
+
+### GraphQL Overview
+
+GraphQL allows developers to communicate with the platformOS backend. It is used to query and mutate data, offering control over the information returned or modified. In platformOS, this is particularly helpful for tasks such as database management, user authentication, or integrating third-party services like email or SMS. GraphQL provides developers with a powerful alternative to Liquid, enabling highly tailored queries and mutations for a wide range of use cases.
+
+- [What is platformOS — GraphQL](/developer-guide/about-platformos/about-platformos#graphql)
+- [Introduction to GraphQL](https://graphql.org/learn)
+- [The Fullstack Tutorial for GraphQL](https://www.howtographql.com)
+
+## Setting up your IDE for GraphQL
+
+Before diving into writing GraphQL queries and mutations on platformOS, it's important to set up your development environment correctly. The platformOS workflow includes dedicated steps for configuring your IDE to work with GraphQL. Proper configuration ensures that you can make full use of autocompletion and syntax highlighting, streamlining the development process.
+
+**Learn how to set up your IDE for GraphQL**: [Development Workflow – Setup IDE for GraphQL](/developer-guide/platformos-workflow/development-workflow#5-setup-ide-graphql)
+
+{% include 'alert/tip', content: 'Learn how to <a href="/developer-guide/platformos-workflow/development-workflow#5-setup-ide-graphql">set up your IDE for GraphQL</a>.' %}
+
+## Using GraphQL in platformOS
+
+Once your development environment is set up, you can start using GraphQL for various tasks, including data retrieval, storage, and integration with other services. platformOS allows you to create and run GraphQL queries and mutations, enabling a wide range of functionalities such as:
+
+- **Retrieving data**: You can query platformOS databases using GraphQL, retrieving only the specific data you need.
+- **Mutations**: GraphQL is also used to perform mutations—actions that modify data, such as creating, updating, or deleting records.
+
+For example, you can use GraphQL to send emails or trigger HTTP requests, and even interact with PostgreSQL databases to create or update records.
+
+- [Retrieving and Presenting Data example tutorial](/developer-guide/pages/retrieving-presenting-data)
+
+### GraphQL Query and Mutation Glossary
+To get the most out of GraphQL, it's essential to understand the terms and structures involved in querying and mutating data. The platformOS **GraphQL Glossary** provides definitions for key concepts like fields, arguments, and directives, with specific examples showing how to use them within platformOS.
+
+- [GraphQL Glossary](/developer-guide/glossary#graphql)
+
+### **Key Features and Use Cases**
+GraphQL on platformOS enables a wide variety of use cases, such as:
+
+1. **Data retrieval**: Using queries to fetch only the necessary data, improving performance and efficiency.
+2. **Data mutation**: Creating, updating, or deleting records in the platformOS database with precision.
+3. **Integrations**: Triggering external services (e.g., SendGrid for email, SMS services) using GraphQL mutations.
+4. **Handling properties and filtering**: Customizing queries to retrieve or filter specific properties from database records based on flexible criteria.
+
+{% include 'alert/tip', content: 'Learn more about querying and mutating <a href="/api-reference/properties">Properties</a>.' %}
+
+## Getting Started with GraphQL
+
+To begin working with GraphQL on platformOS, follow these steps:
+1. **[Set up your IDE](/developer-guide/platformos-workflow/development-workflow#5-setup-ide-graphql)** for GraphQL to enable autocompletion and syntax validation.
+2. **Familiarize yourself with the [GraphQL Glossary](/api-reference/graphql/glossary)** to understand the basic terminology.
+3. **Start with simple queries** to fetch data, and use mutations for creating or updating records.
+
+## Resources for Learning GraphQL
+
+**Introduction to GraphQL**:  
+This is the official introduction to GraphQL, explaining the core concepts and how GraphQL works.  
+- [Introduction to GraphQL](https://graphql.org/learn)
+
+**The Fullstack Tutorial for GraphQL**:  
+A comprehensive tutorial for learning GraphQL from scratch. It covers both frontend and backend development, with examples in multiple programming languages.  
+- [The Fullstack Tutorial for GraphQL](https://www.howtographql.com)
+
+**Set up your IDE for GraphQL**:  
+Learn how to configure your IDE for GraphQL, enabling autocompletion, syntax validation, and better development workflow on platformOS.  
+- [Set up your IDE for GraphQL](/developer-guide/platformos-workflow/development-workflow#5-setup-ide-graphql)
+
+**GraphQL vs Liquid Directory Structure**:  
+Learn the differences between the directory structure for Liquid and GraphQL in platformOS. This guide outlines which directories are necessary for each and provides clarity on how to use them effectively in your projects.  
+- [GraphQL vs Liquid Directory Structure](https://alex-docs-preview.staging.oregon.platform-os.com/developer-guide/platformos-workflow/directory-structure/graphql-liquid-directories)
+
+**GraphQL Glossary**:  
+This glossary explains core GraphQL terms such as **arguments**, **aliases**, and **directives**. It provides practical examples on how these terms are used within platformOS implementations.  
+- [GraphQL Glossary](/api-reference/graphql/glossary)
+
+**Retrieving and Presenting Data**:  
+This guide walks you through retrieving data using GraphQL queries and presenting it on a web page via Liquid. It also explains how to test queries using the GraphiQL tool.  
+- [Retrieving and Presenting Data](/developer-guide/pages/retrieving-presenting-data)
+
+**Feeding Data into AMP Pages with GraphQL**:  
+Learn how to use GraphQL queries to display product data in AMP (Accelerated Mobile Pages), integrating JSON endpoints with AMP structures.  
+- [Feeding Data into AMP Pages](/api-reference/graphql/amp-pages)
+
+**Saving Data to the Database**:  
+This tutorial shows how to use GraphQL mutations to store and remove data in platformOS databases, and includes steps for creating a GraphQL mutation for inserting records.  
+- [Saving Data to the Database](/developer-guide/databases/saving-data)
+
+**Loading Related Records**:  
+This guide explains how to load related records efficiently using GraphQL. It addresses common issues like n+1 queries and provides examples of joining records within a single query for better performance.  
+- [Loading Related Records](/developer-guide/records/loading-related-records)
+
+**Properties Guide**:  
+Covers how to define and retrieve properties in platformOS. It explains how to use GraphQL to query and filter properties based on various data types.  
+- [Properties](/api-reference/properties)
+
+**GraphQL vs Liquid Directory Structure**:  
+Learn the differences between the directory structure for Liquid and GraphQL in platformOS. This guide outlines which directories are necessary for each and provides clarity on how to use them effectively in your projects.  
+- [GraphQL vs Liquid Directory Structure](/developer-guide/platformos-workflow/directory-structure/graphql-liquid-directories)

app/views/pages/developer-guide/graphql/using-graphql.liquid

@@ -0,0 +1,59 @@
+---
+converter: markdown
+metadata:
+  title: Using GraphQL without Liquid
+  description: This guide explains how you can use GraphQL on platformOS without relying on Liquid, covering database management, integrations, and advanced functionality through GraphQL queries and mutations.
+---
+
+On platformOS, many tasks have traditionally been approached using **Liquid**. While Liquid remains a powerful tool, **GraphQL** offers another pathway to achieve nearly everything you need—without relying on Liquid. This article provides an overview of **how GraphQL can be used as the primary tool for interacting with platformOS** and explores how we're shifting toward more GraphQL-centric documentation and examples.
+
+### **The Two Journeys: Liquid vs. GraphQL**
+
+There are two main journeys developers can take when working with platformOS:
+
+1. **Liquid + GraphQL Journey**:  
+   This is the path we’ve traditionally documented. It involves using **Liquid** for rendering pages, layouts, and handling other frontend elements, with **GraphQL** acting as the engine that powers data queries and mutations.
+
+2. **GraphQL-Only Journey**:  
+   For those working with frameworks like **Next.js**, **Node.js**, or **Python**, Liquid might not be necessary. Instead, you can handle all your backend interactions with GraphQL alone, making calls to the **platformOS API** to manage your data, send emails, or trigger HTTP requests. This approach allows you to bypass Liquid entirely.
+
+## Why Shift the Focus to GraphQL?
+
+**GraphQL** is a flexible, efficient query language that allows developers to communicate directly with platformOS’ backend. It gives you control over your data: whether you need to read from or write to the database, interact with external services, or manage files. While much of our current documentation has been built around using Liquid, **almost everything is achievable through GraphQL**. For many developers, this can be a cleaner and more efficient approach.
+
+- [Introduction to GraphQL](https://graphql.org/learn)
+- [The Fullstack Tutorial for GraphQL](https://www.howtographql.com)
+
+## Exploring What’s Possible with GraphQL
+
+**GraphQL on platformOS** unlocks a range of powerful features for managing data and interacting with the platform's backend. Here's what you can achieve using GraphQL:
+
+- **Database Management (PostgreSQL)**: GraphQL allows you to define, manage, and query your **database schema** in platformOS. Through the **`schema/` directory**, you define the structure of your data (tables and fields) and use GraphQL queries and mutations to interact with this data. This involves managing **Records and Tables** (custom objects and their data). For more details, check out the [Building Contact Form with Records guide](/developer-guide/records/building-contact-form-with-records) and the [Records and Tables guide](/developer-guide/records/records-tables).
+
+- **[ElasticSearch](/developer-guide/json-documents/json-documents)**: GraphQL makes it easy to set up and interact with **ElasticSearch** for advanced search functionality. You can define search configurations and mappings directly via GraphQL to implement efficient search features for your data.
+
+- **[Activity Feeds](/developer-guide/activity-feeds/activity-feeds)**: Using GraphQL, you can manage **Activity Streams**, allowing you to track user activities and events. This functionality is useful for creating real-time updates, tracking notifications, and managing logs.
+
+- **[AI - Embeddings](/developer-guide/embeddings/embeddings)**: With GraphQL, you can manage **AI embeddings**, storing and retrieving vector representations of data for use in machine learning models or other AI-driven applications. This is particularly useful for developers looking to integrate AI functionalities into their platformOS projects.
+
+- **[User Uploads](/developer-guide/user-uploads/user-uploads)**: Handle **file uploads** easily through GraphQL, allowing users to upload, store, and manage files such as images, documents, and media without needing Liquid. This provides flexibility in managing files directly from the GraphQL API.
+
+- **[Creating an API Call Notification](/developer-guide/notifications/creating-api-call-notification)**: Use the `api_call_send` mutation to make HTTP requests from platformOS, enabling you to connect to external services or APIs, such as third-party applications, payment gateways, or external systems.
+
+- **[Creating an SMS Notification](/developer-guide/notifications/creating-sms-notification)**: Use the `sms_send` mutation to integrate with services like Twilio, sending SMS notifications when certain events occur (e.g., user sign-up).
+
+- **External Integrations**: In addition to the above, GraphQL allows you to send emails (`email_send` mutation) and trigger external APIs using `api_call_send`, providing a more API-driven approach to external service integrations without the need for Liquid templates.
+
+## Schema and GraphQL Without Liquid
+
+In the **schema** chapter of our developer guide, we’ve historically combined Liquid and GraphQL, which can be confusing. For example, in the [Building a Contact Form with Records](/developer-guide/records/building-contact-form-with-records) guide, we show how to create records using a combination of GraphQL and Liquid, but it can leave developers wondering if Liquid is necessary.
+
+Our goal moving forward is to **separate the two journeys**:
+- **Liquid + GraphQL**: Continue to provide tutorials that show how to use both technologies together.
+- **GraphQL-Only**: Highlight what’s possible with GraphQL on its own, focusing on **schema**, **queries**, and **mutations**.
+
+For developers asking if platformOS can be used **without Liquid**, the answer is: *yes, kind of*. You don’t need Liquid for handling the database, ElasticSearch, or managing integrations—but there are certain areas, like email templates, where Liquid is still required (for now). That said, we are working towards making email, API calls, and SMS functionality **fully accessible via GraphQL** without requiring Liquid templates.
+
+This will serve as a starting point for developers who want to explore the possibilities of platformOS without Liquid.
+
+Our goal moving forward is to ensure that developers can fully explore the **GraphQL-only journey** by providing tutorials, examples, and more documentation to show how **GraphQL** can manage everything from database interactions to integrations.

app/views/pages/developer-guide/platformos-workflow/directory-structure/graphql-liquid-directories.liquid

@@ -0,0 +1,90 @@
+---
+converter: markdown
+metadata:
+  title: Liquid vs GraphQL Directories
+  description: Understanding the Directory Structure for Liquid and GraphQL
+---
+
+When working with platformOS, understanding which directories are used for **Liquid** and which are used for **GraphQL** is essential to keeping your project organized. Depending on whether you're using Liquid, GraphQL, or both, some directories will be more important than others. Let’s break it down:
+
+## Liquid-Only Directories
+If your project is primarily using **Liquid**, you’ll need these specific directories for handling your page layouts, templates, and logic:
+
+### `graphql/` directory
+**Surprise!** This directory is needed when using Liquid, even though it’s named after GraphQL. It stores the queries and mutations that Liquid uses to fetch or modify data. If you’re working exclusively with GraphQL, you won’t need this directory.
+
+### `views/` directory 
+This is where your Liquid templates live, including:
+   - **`views/pages`**: Your page templates go here.
+   - **`views/layouts`**: This directory handles the overall structure of your site (e.g., headers and footers).
+   - **`views/partials`**: Contains reusable components like forms or widgets.
+
+If you’re not using Liquid, these directories will remain empty.
+
+### `lib/` directory 
+Contains helper functions and logic files that are used by Liquid. Think of this directory as the brains behind your Liquid templates!
+If you’re working purely with GraphQL, you won’t need anything in `lib/`.
+
+### `authorization_policies/` directory  
+This directory is used to define who can access what—written entirely in Liquid.
+
+### `translations/`directory
+If your platform supports multiple languages, this directory stores all the translation files, written in Liquid.
+
+### `migrations/` directory   
+Migrations are used to modify the database structure and are written in Liquid, so you don’t need this directory for GraphQL-based projects.
+
+### `emails/`, `api_calls/`, and `smses/` directory 
+These directories contain **Liquid templates** that are currently required for sending emails, making API calls, or sending SMS messages. This is because, right now, the process relies on Liquid for the templates that define these messages.
+
+**For now, these are Liquid-only**: Even if you're using **GraphQL** for sending emails, API calls, or SMS messages, you still need to reference a **Liquid template** stored in the `emails/` directory. For example, when using the `email_send` mutation in GraphQL, a `template` must be specified, and that template corresponds to a file located in `app/email/template`, which is written in Liquid.
+
+Here’s an example of the current setup:
+
+```graphql
+mutation send_email {
+  email_send (
+    template: "welcome_email"
+  )
+}
+```
+
+### `config.yml` file  
+This file configures key aspects of your site and is needed only for Liquid-based setups.
+
+## **GraphQL-Only Directories**
+If you're focusing on using just **GraphQL** in your platformOS project, here’s what you need:
+
+### `assets/` directory
+This directory is used to store static files like images, CSS, JavaScript, etc. You can reference these assets through Liquid or GraphQL.
+**Used for both**: You can query for assets using GraphQL without needing Liquid.
+
+Example:
+
+```graphql
+     query get_assets {
+       admin_assets {
+         results {
+           name
+         }
+       }
+     }
+```
+### `user.yml` file  
+This is the **GraphQL schema** file for user data. It defines how user data is structured and how you can query or mutate user information.
+**Only for GraphQL**: You’ll need this file to manage users, but not for Liquid-based projects.
+
+### **Directory Overview Table**
+
+| **Directory/File**            | **Used for Liquid** | **Used for GraphQL** | **Notes**                                                  |
+|-------------------------------|---------------------|----------------------|------------------------------------------------------------|
+| `graphql/`                    | Yes                 | No                   | Needed for Liquid to handle GraphQL queries/mutations.      |
+| `views/`                      | Yes                 | No                   | Contains Liquid templates for pages, layouts, and partials. |
+| `lib/`                        | Yes                 | No                   | Stores helper functions used in Liquid templates.           |
+| `authorization_policies/`      | Yes                 | No                   | Defines access control using Liquid.                        |
+| `translations/`               | Yes                 | No                   | Handles translations for Liquid templates.                  |
+| `config.yml`                  | Yes                 | No                   | Configures Liquid project settings.                         |
+| `emails/`, `api_calls/`, `smses/` | Yes              | No (Future: Yes)     | Currently Liquid-based, but GraphQL support is planned.      |
+| `user.yml`                    | No                  | Yes                  | Defines the GraphQL schema for user data.                   |
+| `assets/`                     | Yes                 | Yes                  | Static assets can be used with both Liquid and GraphQL.      |
+| `migrations/`                 | Yes                 | No                   | Handles database migrations, written in Liquid.             |