# hexafield/conjure architecture

> Architecture diagram of the GitHub repository hexafield/conjure, 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/hexafield/conjure
- Repository: https://github.com/hexafield/conjure

## Overview

##### Project Overview & Type
- The project (named “conjure”) is a front-end heavy web application with decentralized collaboration features.
- It integrates immersive world experiences (through iR Engine), decentralized identity/data (via ADAM/Holochain), real-time media support, and p2p signalling.
- The README outlines progress items like connecting to ADAM, retrieving perspectives/neighbourhoods, and p2p signalling, which suggests critical integration points.

##### File Structure
- Top-level Files:
- index.html, manifest.json, package.json, and server.js indicate both a static front end and a Node.js backend component.
- Configuration files (postcss.config.js, tailwind.config.js, tsconfig.json, vite.config.ts, xrengine.config.ts) expose the technical stack (Vite, Tailwind, XR Engine).
- Source Code (src Directory):
- “ad4m” Folder: Contains modules and custom hooks (e.g., useADAM, useNeighbourhoodNetwork, usePerspectives, createAd4mAPIAdapter) that handle interactions with ADAM/Holochain services.
- “world” Folder: Hosts components and hooks (e.g., BasicScene, NeighbourhoodBubbles, useSpawnAvatar) likely responsible for rendering immersive 3D or XR content.
- “tools/graph” Folder: Comprises several components and utility functions (e.g., DataGrapher, DataPipeline, ForceGraph) for graphing or visualization, probably to map relationships in neighborhoods and perspectives.
- “utils” Folder: Supports utility functions across modules.

##### Main Components & Their Interactions
a. Client/Frontend:
- Built with modern JavaScript/TypeScript frameworks (hints from .tsx files, Vite, and Tailwind).
- Composed of React-based UI components (CustomLocationPage, components from world and graph subdirectories) that render immersive scenes and data visualizations.
- Entry point: src/main.tsx and index.html.

b. Decentralized Integration Layer:
- The “ad4m” modules encapsulate logic for connecting to ADAM/Holochain. They support tasks like fetching perspectives, managing neighborhood networks, and interfacing with decentralized APIs.
- These components manage the p2p signalling and connection layers required for decentralized collaboration.

c. Immersive World & XR Integration:
- The “world” components (BasicScene, NeighbourhoodBubbles, NeighbourhoodWorldSystem) provide the virtual environment.
- Integration with the XR Engine is signified by the xrengine.config.ts file, ensuring immersive experiences.

d. Graph & Visualization Tools:
- Located in “src/tools/graph,” these components (DataGrapher, ForceGraph, MappingUI) show how data (such as inter-user relationships, neighborhood mappings, and schema) is handled visually.
- They likely interface with the core state management and real-time data pipelines.

e. Backend/Server:
- The presence of a server.js file suggests a Node.js server that might serve static files or handle backend integration.
- GitHub workflows under “.github/workflows” (e.g., deploy-static.yml, project-build.yml) imply CI/CD pipelines to build, test, and deploy both the static front end and potentially server endpoints.

##### Architectural Patterns & Design
- The project naturally separates concerns into distinct modules:
- UI rendering and user interaction (React components).
- Decentralized network and data management (AD4M/ADAM integration).
- Real-time and immersive world generation (XR and 3D environment components).
- Data visualization via a dedicated graph tooling module.
- The design likely follows component-based architecture and modular design, with each subfolder representing a domain (or “service”) in the system.
- Inter-module communication (e.g., between the ad4m and world modules) is managed via React hooks and possibly context/state management libraries.

- Frontend Client: Label with “React UI” (maybe indicate index.html & main.tsx as entrypoint).
- Decentralized Service Layer: Label with “AD4M/ADAM Integration” (include custom hooks like useADAM, useNeighbourhoodNetwork, and usePerspectives).
- Immersive World Module: Label with “World Engine/XR Integration” (include components such as BasicScene, NeighbourhoodBubbles).
- Graph & Visualization Tools: Label with “Data Graphing & Visualization” (include DataGrapher, ForceGraph, etc.).
- “iR Engine” and “Holochain/ADAM” as external integrations.
- Relationships:
- That the immersive world components receive inputs from the decentralized layer.
- If applicable, illustrate the deployment flow through the CI/CD pipeline (GitHub workflows) connecting to the server module.

##### Final Advice for the Principal Software Engineer
- On the interplay between components: the frontend interacts with decentralized services (ad4m), which then feed data to both immersive world rendering and graph visualization tools.
- Since this is a full-stack application with specialized integration, maintaining clarity in how these layers interact (especially the decentralized aspects and real-time media support) is key.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Client Subgraph
    subgraph "Frontend Client"
        a1["index.html"]:::frontend
        a2["src/main.tsx"]:::frontend
        a3["src/CustomLocationPage.tsx"]:::frontend
    end

    %% Decentralized Service Layer Subgraph
    subgraph "Decentralized Service Layer"
        b1["useADAM.tsx"]:::decentralized
        b2["useNeighbourhoodNetwork.tsx"]:::decentralized
        b3["usePerspectives.ts"]:::decentralized
        b4["createAd4mAPIAdapter.ts"]:::decentralized
    end

    %% Immersive World Module Subgraph
    subgraph "Immersive World Module"
        c1["BasicScene.ts"]:::immersive
        c2["NeighbourhoodBubbles.tsx"]:::immersive
        c3["NeighbourhoodWorldSystem.tsx"]:::immersive
        c4["useSpawnAvatar.tsx"]:::immersive
        c5["xrengine.config.ts"]:::immersive
    end

    %% Graph & Visualization Tools Subgraph
    subgraph "Graph & Visualization Tools"
        d1["DataGrapher.tsx"]:::graphing
        d2["DataPipeline.tsx"]:::graphing
        d3["ForceGraphRaw.tsx"]:::graphing
        d4["MappingUI.tsx"]:::graphing
        d5["SchemaDisplay.tsx"]:::graphing
        d6["Graph Components (subdir)"]:::graphing
        d7["Graph Forcegraph (subdir)"]:::graphing
        d8["Graph Functions (subdir)"]:::graphing
    end

    %% Backend Server Subgraph
    subgraph "Backend Server"
        e1["server.js"]:::backend
    end

    %% CI/CD Pipelines Subgraph
    subgraph "CI/CD Pipelines"
        f1["deploy-static.yml"]:::cicd
        f2["project-build.yml"]:::cicd
    end

    %% External Integrations
    g1["iR Engine"]:::external
    g2["Holochain/ADAM"]:::external

    %% Connections
    a2 -->|"requestsData"| b1
    a2 -->|"initImmersive"| c1
    a3 -->|"visualizesMapping"| d4

    b4 -->|"connectsTo"| g2
    b2 -->|"updatesWorld"| c4
    b3 -->|"feedsGraphData"| d1

    d2 -->|"pipelinesData"| d1
    d3 -->|"rendersGraph"| d1
    d5 -->|"schemaMapping"| c3

    c5 -->|"XRIntegration"| g1

    f1 -->|"deploys"| e1
    f2 -->|"builds"| e1

    a1 -->|"servedBy"| e1

    %% Class Definitions for styling
    classDef frontend fill:#F7A072,stroke:#333,stroke-width:2px;
    classDef decentralized fill:#C2E7DA,stroke:#333,stroke-width:2px;
    classDef immersive fill:#C4DEF6,stroke:#333,stroke-width:2px;
    classDef graphing fill:#FDEBD0,stroke:#333,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef cicd fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#333,stroke-width:2px;

    %% Click Events for Frontend Client
    click a1 "https://github.com/hexafield/conjure/blob/master/index.html"
    click a2 "https://github.com/hexafield/conjure/blob/master/src/main.tsx"
    click a3 "https://github.com/hexafield/conjure/blob/master/src/CustomLocationPage.tsx"

    %% Click Events for Decentralized Service Layer
    click b1 "https://github.com/hexafield/conjure/blob/master/src/ad4m/useADAM.tsx"
    click b2 "https://github.com/hexafield/conjure/blob/master/src/ad4m/useNeighbourhoodNetwork.tsx"
    click b3 "https://github.com/hexafield/conjure/blob/master/src/ad4m/usePerspectives.ts"
    click b4 "https://github.com/hexafield/conjure/blob/master/src/ad4m/createAd4mAPIAdapter.ts"

    %% Click Events for Immersive World Module
    click c1 "https://github.com/hexafield/conjure/blob/master/src/world/BasicScene.ts"
    click c2 "https://github.com/hexafield/conjure/blob/master/src/world/NeighbourhoodBubbles.tsx"
    click c3 "https://github.com/hexafield/conjure/blob/master/src/world/NeighbourhoodWorldSystem.tsx"
    click c4 "https://github.com/hexafield/conjure/blob/master/src/world/useSpawnAvatar.tsx"
    click c5 "https://github.com/hexafield/conjure/blob/master/xrengine.config.ts"

    %% Click Events for Graph & Visualization Tools
    click d1 "https://github.com/hexafield/conjure/blob/master/src/tools/graph/DataGrapher.tsx"
    click d2 "https://github.com/hexafield/conjure/blob/master/src/tools/graph/DataPipeline.tsx"
    click d3 "https://github.com/hexafield/conjure/blob/master/src/tools/graph/ForceGraphRaw.tsx"
    click d4 "https://github.com/hexafield/conjure/blob/master/src/tools/graph/MappingUI.tsx"
    click d5 "https://github.com/hexafield/conjure/blob/master/src/tools/graph/SchemaDisplay.tsx"
    click d6 "https://github.com/hexafield/conjure/tree/master/src/tools/graph/components"
    click d7 "https://github.com/hexafield/conjure/tree/master/src/tools/graph/forcegraph"
    click d8 "https://github.com/hexafield/conjure/tree/master/src/tools/graph/functions"

    %% Click Event for Backend Server
    click e1 "https://github.com/hexafield/conjure/blob/master/server.js"

    %% Click Events for CI/CD Pipelines
    click f1 "https://github.com/hexafield/conjure/blob/master/.github/workflows/deploy-static.yml"
    click f2 "https://github.com/hexafield/conjure/blob/master/.github/workflows/project-build.yml"
```
