# appointy/jaal architecture

> Architecture diagram of the GitHub repository appointy/jaal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/appointy/jaal
- Repository: https://github.com/appointy/jaal

## Overview

##### Main Components
- HTTP Server Frontend – This is the entry point for GraphQL requests (using the jaal.HTTPHandler and the main function that calls http.ListenAndServe on "/graphql").
- GraphQL Schema Builder (schemabuilder package) – This component is responsible for registering objects, fields, enums, inputs, mutations, and queries. The schemabuilder collects all the GraphQL types and resolvers from user registration functions.
- Core GraphQL Engine (graphql package) – This module contains parsing, executing, validating, and even lazy execution and union/union tests. It is where the query lifecycle happens (from parsing requests to executing the registered resolvers).
- Introspection Module (introspection package) – Adds support for GraphQL introspection queries to the built schema.
- Custom Scalar and Type Handling – These functionalities are visible in both the custom scalar registration examples in the README (and supported in the code via registration functions) and the definitions in gtypes.
- Error Handling Module (jerrors package) – Manages error propagation and formatting.
- Client and Example Implementations – The example directory includes different implementations (Go clients and JavaScript clients), which demonstrate how a GraphQL client can interact with the server.
- Utility & Internal Packages – The internal package (like internal/json.go) and others such as ws.go (websockets) support utility functions and additional transport protocols.

##### Relationships and Data Flow
- The HTTP Server receives GraphQL requests and passes them to the GraphQL Engine where the query is parsed (using parser.go and validate.go from the graphql package).
- The GraphQL Engine relies on the schema built by the schemabuilder. Thus, the schemabuilder feeds the engine with the definition of objects, queries, and mutations.
- Once the query is executed, the execution module (such as execute.go) will invoke the associated resolver functions (registered via FieldFunc calls) to fetch or modify data.
- The introspection module sits logically “as a layer” that integrates into the schema to include GraphQL introspection capabilities.
- Custom scalars and types are registered early in the schema-building phase, altering the behavior of how inputs and outputs (like dates or other scalars) are processed.
- Tests (both unit and integration) and various example clients show how different parts of the framework interact, ensuring the flow from client invocation to data processing.

##### Architectural Patterns and Design Principles
- Modular Design – The project is divided into clear packages (schemabuilder, graphql, introspection, etc.) each responsible for a distinct aspect of the GraphQL server functionality.
- Separation of Concerns – The HTTP layer, schema building, query execution, and introspection are clearly isolated.
- Extensibility – By allowing the registration of custom scalars, inputs, enums, interfaces, and unions, the framework shows a design driven by extensibility.
- Testing and Examples – The repository includes a robust example directory and tests that provide sample flows and demonstrate client-server interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["GraphQL Client"]:::client

    %% HTTP Layer Subgraph
    subgraph "HTTP Layer"
        HTTP["HTTP Server Endpoint (jaal.HTTPHandler)"]:::http
        Utility["Utility (internal)"]:::support
        Websocket["WebSocket Support"]:::support
    end

    %% GraphQL Core Engine Subgraph
    subgraph "GraphQL Core Engine"
        Parser["Parser"]:::engine
        Validator["Validator"]:::engine
        Executor["Executor"]:::engine
    end

    %% Schema Building Subgraph
    subgraph "Schema Building"
        SchemaBuilder["Schema Builder"]:::schema
        CustomScalar["Custom Scalar & Type Registration"]:::schema
    end

    %% Supporting Modules Subgraph
    subgraph "Supporting Modules"
        Introspection["Introspection Module"]:::support
        ErrorHandling["Error Handling Module"]:::support
    end

    %% Example Clients Subgraph
    subgraph "Client Implementations"
        Example["Example Clients"]:::example
    end

    %% Connections
    Client -->|"sends request"| HTTP
    HTTP -->|"forwards request"| Parser
    Parser -->|"parses query"| Validator
    Validator -->|"validates query"| Executor
    Executor -->|"handles errors"| ErrorHandling
    Executor -->|"returns response"| Client

    %% Schema Building integrated into GraphQL Engine
    SchemaBuilder -->|"provides schema"| Parser
    CustomScalar -->|"augments"| SchemaBuilder
    Introspection -->|"integrates introspection"| SchemaBuilder

    %% Utility connections supporting HTTP layer
    HTTP ---|"uses"| Utility
    HTTP ---|"supports"| Websocket

    %% Example Clients usage
    Example -->|"invokes endpoint"| HTTP
    Example -->|"demonstrates usage"| Client

    %% Click Events
    click HTTP "https://github.com/appointy/jaal/blob/master/http.go"
    click SchemaBuilder "https://github.com/appointy/jaal/tree/master/schemabuilder/"
    click Parser "https://github.com/appointy/jaal/blob/master/graphql/parser.go"
    click Validator "https://github.com/appointy/jaal/blob/master/graphql/validate.go"
    click Executor "https://github.com/appointy/jaal/blob/master/graphql/execute.go"
    click Introspection "https://github.com/appointy/jaal/tree/master/introspection/"
    click CustomScalar "https://github.com/appointy/jaal/blob/master/gtypes/global.go"
    click ErrorHandling "https://github.com/appointy/jaal/tree/master/jerrors/"
    click Example "https://github.com/appointy/jaal/tree/master/example/"
    click Utility "https://github.com/appointy/jaal/tree/master/internal/"
    click Websocket "https://github.com/appointy/jaal/blob/master/ws.go"

    %% Styles
    classDef http fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef engine fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef schema fill:#f94144,stroke:#333,stroke-width:2px;
    classDef support fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef client fill:#577590,stroke:#333,stroke-width:2px;
    classDef example fill:#43aa8b,stroke:#333,stroke-width:2px;
```
