# kindlyops/havengrc architecture

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

- Interactive diagram: https://gitdiagram.com/kindlyops/havengrc
- Repository: https://github.com/kindlyops/havengrc

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external

    %% Gateway
    subgraph "Gateway"
        G1["Gatekeeper (Caddy)"]:::gateway
    end

    %% Frontend
    subgraph "Frontend"
        UI["Web User Interface (Elm)"]:::frontend
    end

    %% Authentication
    subgraph "Authentication"
        KC["Keycloak"]:::auth
        KSP["Service Providers"]:::auth
    end

    %% Backend
    subgraph "Backend"
        API["API Service (havenapi)"]:::backend
        DB["Database (PostgreSQL)"]:::database
        MIG["Flyway Migrations"]:::backend
        Worker["Background Worker"]:::backend
    end

    %% Infrastructure
    subgraph "Infrastructure"
        CICD["CI/CD (.circleci)"]:::infrastructure
        Grafana["Monitoring (Grafana)"]:::infrastructure
        Prom["Monitoring (Prometheus)"]:::infrastructure
        K8S["Container Orchestration (K8s)"]:::infrastructure
    end

    %% Main Flow
    User -->|"HTTP_Request"| G1
    G1 -->|"Routes_Request"| UI
    UI -->|"API_Request"| API
    API -->|"DB_Query"| DB
    API -->|"Trigger_Migration"| MIG
    API -->|"Queue_Job"| Worker
    UI -->|"Fetch_JWT"| KC
    API -->|"JWT_Validation"| KC
    KC -->|"Utilizes"| KSP
    API -->|"Built_by"| CICD
    API -->|"Deployed_to"| K8S

    %% Monitoring Links
    G1 -->|"Metrics"| Grafana
    API -->|"Metrics"| Prom
    Worker -->|"Metrics"| Grafana

    %% Click Events
    click UI "https://github.com/kindlyops/havengrc/tree/master/webui/"
    click API "https://github.com/kindlyops/havengrc/tree/master/havenapi/"
    click KC "https://github.com/kindlyops/havengrc/tree/master/keycloak/"
    click KSP "https://github.com/kindlyops/havengrc/tree/master/keycloak-service-providers/"
    click Worker "https://github.com/kindlyops/havengrc/tree/master/worker/"
    click MIG "https://github.com/kindlyops/havengrc/tree/master/flyway/"
    click G1 "https://github.com/kindlyops/havengrc/tree/master/gatekeeper/"
    click CICD "https://github.com/kindlyops/havengrc/tree/master/.circleci/"
    click Grafana "https://github.com/kindlyops/havengrc/tree/master/grafana/"
    click Prom "https://github.com/kindlyops/havengrc/tree/master/prometheus/"
    click K8S "https://github.com/kindlyops/havengrc/tree/master/k8s/"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px
    classDef gateway fill:#98FB98,stroke:#333,stroke-width:2px
    classDef frontend fill:#87CEFA,stroke:#333,stroke-width:2px
    classDef auth fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef backend fill:#B0C4DE,stroke:#333,stroke-width:2px
    classDef database fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef infrastructure fill:#D3D3D3,stroke:#333,stroke-width:2px
```
