# hashicorp-forge/hermes architecture

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

## Overview

##### Project Type & Purpose
- Hermes is an open source document management system in the alpha stage. It is designed to help organizations manage document creation, publication, approvals, and revision tracking.
- It integrates multiple external services such as Google Workspace for document management and email, Algolia for search indexing, and optionally Jira for issue tracking.
- The system is composed of a Go-based backend with several well-organized packages plus an embedded Ember.js frontend.

##### Main Components
- Frontend – The Ember.js web application, found under the “web” directory. This portion handles user interactions, routing, displaying documents, and dashboard functions.
- Server – The main Go-based server (built via cmd/hermes and internal/server) that:
- Serves web content and API endpoints.
- Provides proxy endpoints (e.g., the /1/ Algolia proxy and /l/ human-readable redirect links).
- Embeds and serves the Ember.js frontend.
- Indexer – A distinct process (see internal/cmd/commands/indexer and internal/indexer) that:
- Polls for updates in published documents.
- Updates document metadata.
- Reindexes documents in Algolia to keep search results current.
- Database – PostgreSQL is the persistent storage for non-search application data (supported via internal/db).
- External Integrations:
- Google Workspace Services – APIs for Drive, Docs, Gmail, People, along with OAuth credentials support (internal/auth, pkg/googleworkspace).
- Algolia – For search indexing (pkg/algolia and corresponding configuration in README).
- Optional Jira Integration – Components for linking documents with Jira issues (internal/api/v2/jira_issue.go and similar).

##### Interactions and Relationships
- The Ember.js frontend communicates with the server over RESTful endpoints for user authentication, document retrieval, and administrative actions.
- The server:
- Handles user authentication (via Google OAuth, Okta, etc. in internal/auth).
- Serves API endpoints and acts as a proxy for Algolia queries.
- Embeds the frontend into the binary to serve static assets.
- The Indexer runs in parallel to continuously poll for document changes (reading from Google Drive/Docs and the Postgres store) and pushes updates to Algolia.
- The database (PostgreSQL) is central for storing document data, user information, and related metadata.
- External APIs (Google and Algolia) establish bidirectional communication:
- Google APIs are used for document operations, email notifications, and authentication.
- Algolia is updated via the indexer (and maybe used to power search results) as well as proxied for client requests.

##### Architectural Patterns & Technologies
- Separation of Concerns is evident:
- The backend is clearly segmented into API, authentication, email, database, and indexing components (indicated by directories like internal/api, internal/auth, internal/email, internal/db, and internal/indexer).
- The Ember.js frontend is fully decoupled and resides in its own “web” directory.
- Microservices or process isolation is visible with the independent “server” and “indexer” processes.
- Deployment aspects such as Docker Compose (docker-compose.yml) are included for supporting PostgreSQL locally.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        FE["Ember.js Frontend<br/>(User Interface)"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        GS["Go Server<br/>(API, Static Content, OAuth)"]:::backend
        IDX["Indexer Process<br/>(Document Polling & Algolia Reindexing)"]:::backend
    end

    %% Data Storage
    subgraph "Data Storage"
        DB["PostgreSQL Database"]:::database
    end

    %% External Services
    subgraph "External Services"
        GW["Google Workspace APIs<br/>(Drive, Docs, Gmail, OAuth)"]:::external
        ALG["Algolia Search Service"]:::external
        JIRA["Optional Jira Integration"]:::external
    end

    %% Connections
    FE -->|"HTTP/REST"| GS
    GS -->|"CRUD"| DB
    IDX -->|"Polls & Updates"| DB
    IDX -->|"Updates Search Index"| ALG
    GS -->|"Calls"| GW
    GS -->|"Proxy /1/ for Search"| ALG
    GS -->|"Issue Linking"| JIRA

    %% Click Events for Component Mapping
    click FE "https://github.com/hashicorp-forge/hermes/tree/main/web"
    click GS "https://github.com/hashicorp-forge/hermes/tree/main/cmd/hermes"
    click GS "https://github.com/hashicorp-forge/hermes/blob/main/internal/server/server.go"
    click IDX "https://github.com/hashicorp-forge/hermes/blob/main/internal/cmd/commands/indexer/indexer.go"
    click IDX "https://github.com/hashicorp-forge/hermes/tree/main/internal/indexer/"
    click DB "https://github.com/hashicorp-forge/hermes/blob/main/internal/db/db.go"
    click GW "https://github.com/hashicorp-forge/hermes/tree/main/internal/auth/google/"
    click GW "https://github.com/hashicorp-forge/hermes/tree/main/pkg/googleworkspace/"
    click ALG "https://github.com/hashicorp-forge/hermes/tree/main/pkg/algolia/"
    click JIRA "https://github.com/hashicorp-forge/hermes/blob/main/internal/api/v2/jira_issue.go"

    %% Styles
    classDef frontend fill:#8ecae6,stroke:#023047,stroke-width:2px;
    classDef backend fill:#ffb703,stroke:#fb8500,stroke-width:2px;
    classDef database fill:#219ebc,stroke:#023047,stroke-width:2px;
    classDef external fill:#8ac926,stroke:#198754,stroke-width:2px;
```
