How hashicorp-forge/hermes works
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.