How kindlyops/havengrc works
Your Main Components
• User Interface (WebUI): Built with Elm, powered by webpack and SASS. It interacts with the user and is deployed with its own Dockerfile and development configurations.
• API Service (“havenapi”): A Go-based service (using Buffalo for task management) that contains the business logic (e.g., risk analysis, reporting, and compliance management). It interacts with models, database migrations (managed via Flyway), and supports endpoints that require JWT tokens.
• Authentication & Authorization: Powered by Keycloak along with custom service providers (in the “keycloak” and “keycloak-service-providers” directories). This handles identity (including JWT token issuance with role claims), integration with external identity providers, and drives multi-tenancy in the system.
• Background Processing (Worker): A separate “worker” service (also in Go) that processes asynchronous tasks such as report generation, email notifications, or other background jobs. It integrates with Faktory to manage job queuing.
• Database and Migrations: A PostgreSQL database managed through Flyway migrations to ensure consistent schema updates.
• Reverse Proxy / Gatekeeper: A “gatekeeper” component (using Caddy) manages web traffic, SSL termination, and serves as the public-facing endpoint.
• Supporting Services & Infrastructure: There are many Docker and Kubernetes configuration files (in k8s/ and related directories), along with monitoring (Grafana, Prometheus), logging, and even email testing (Mailhog). These items are critical for deployment, monitoring, and maintenance in both development and production.
• CI/CD & Build Tools: CircleCI configurations, Bazel build scripts, and Docker-compose files show a continuous integration and containerized deployment approach.
Relationships and Data Flows
• End Users interact with the WebUI, which sends REST API calls to the havenapi service.
• The API Service uses JWT tokens (issued via Keycloak) to authenticate and authorize requests. The flow should show the steps where the client obtains a token (via Keycloak) and then passes it to havenapi.
• The API service communicates with the PostgreSQL database (after migrations applied via Flyway) and may also trigger background jobs.
• The Worker, connected via Faktory, processes asynchronous tasks that originate from user actions performed on the web UI via the API.
• The Gatekeeper (reverse proxy) sits at the application’s edge, routing HTTP(S) requests to the appropriate services (WebUI, Keycloak, etc.).
• Supporting monitoring tools (Grafana, Prometheus), logging, and security-scanning components (Zed Attack Proxy) capture operational metrics and audit information.
Architectural Patterns and Principles
• Microservices/Service-oriented architecture is evident with the clear separation between the front end, API (business logic), authentication, and background processing.
• Separation of concerns: UI, API, Auth, and jobs processing are distinct, and their interactions are governed by standard protocols (HTTP/REST, JWT tokens, etc.).
• Stateless design for API services where possible, with persistent state being managed by PostgreSQL.
Technologies, Libraries, and Frameworks
• Frontend: Elm, webpack, SASS, and Cypress for end-to-end testing.
• Backend: Go, Buffalo framework (with grift tasks for operational commands), Flyway for DB migrations, and Faktory for background job management.
• Authentication: Keycloak (with service providers implemented in Java) and custom JWT configuration.
• Infrastructure: Docker, Kubernetes (with manifests in the k8s/ directory), and monitoring/logging tools (Grafana/Prometheus), as well as reverse proxy (Gatekeeper using Caddy).
• Build Tools: Bazel, Docker-compose, and CircleCI integration.