# l3montree-dev/devguard architecture

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

- Interactive diagram: https://gitdiagram.com/l3montree-dev/devguard
- Repository: https://github.com/l3montree-dev/devguard

## Overview

##### Project type and purpose
- This is the backend of a full-stack application (“DevGuard Backend”) written in Go. It provides:
- A RESTful API (cmd/devguard) for a web frontend and third-party tools
- A CLI (cmd/devguard-cli) for administrative tasks
- A standalone scanner CLI (cmd/devguard-scanner) for vulnerability scanning (SCA, container, IaC, etc.)
- Background daemons for periodic tasks (internal/core/daemon)
- Integration with Ory Kratos for identity, with PostgreSQL for persistence, and external vulnerability data providers (NVD, OSS tools, GitHub/GitLab APIs)

##### File structure
- Top-level directories:
- cmd/devguard           → main API server
- cmd/devguard-cli       → admin CLI entry points (migrate, daemon control, vulndb ops)
- cmd/devguard-scanner   → security scanner CLI
- internal/core          → business logic organized by domain (asset, component, vuln, compliance, integrations, etc.)
– controllers   → HTTP handlers
– services      → core business rules
– repositories  → data access via internal/database
– daemon        → scheduled/background jobs
- internal/database     → GORM models & repositories
- internal/auth         → session & middleware
- internal/echohttp     → HTTP server & middleware
- internal/monitoring   → Prometheus exporters
- charts/devguard       → Helm deployment manifests
- config, Dockerfiles, docker-compose → environment & container setup
- External dependencies:
- Ory Kratos (identity server)
- PostgreSQL
- GitHub/GitLab APIs
- Vulnerability data services (NVD, DebSec, Mitre, etc.)

##### README for additional insights
- Confirms separation between Backend and Web-Frontend
- Backend serves Go REST API and scanner CLI
- Uses Ory Kratos for identity, PostgreSQL for storage, Helm for deployment
- Monitoring & metrics exposed for Prometheus

a. Main components:
1. DevGuard API Server
- HTTP server (Echo)
- Auth middleware (Ory Kratos integration)
- Controllers → Services → Repositories → Database
- Daemon workers (internal/core/daemon)
- Monitoring endpoints (Prometheus exporters)
2. PostgreSQL Database
3. Ory Kratos Identity Service
4. DevGuard-CLI (devguard-cli)
5. DevGuard-Scanner (devguard-scanner)
6. External Vulnerability Providers (NVD, DebSec, Mitre, GitHub Advisory API, etc.)
7. DevGuard Web Frontend (separate project, communicates via REST)
8. Kubernetes & Helm (deployment platform)
b. Relationships & interactions:
- Web Frontend & CLI tools → HTTP(S) → DevGuard API
- API → gRPC/HTTP → Ory Kratos for auth/session
- API → SQL → PostgreSQL
- Daemon workers inside API → pull data from External Providers → update database
- DevGuard-Scanner → HTTP → API (ingest SBOM, scan results)
- Monitoring scrapes API’s Prometheus endpoints
- Helm chart deploys API, Kratos, PostgreSQL on K8s
c. Architectural patterns:
- Layered architecture (Controller → Service → Repository)
- Hexagonal/Onion influences (core logic isolated from transports and persistence)
- CLI adapters on the same codebase, reusing core services
- Background worker pattern for periodic ingestion & tasks
- Integration and adapter modules for external services
d. Key technologies:
- Go with Echo framework
- GORM for DB ORM
- Ory Kratos for identity
- Docker & Helm for containerization & orchestration
- Prometheus metrics exporters
- Casbin or similar for RBAC (internal/accesscontrol)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    WebUI["DevGuard Web Frontend"]:::client
    DevGuardCLI["DevGuard-CLI"]:::client
    ScannerCLI["DevGuard-Scanner"]:::client

    %% External Services
    subgraph "External Services" 
        direction TB
        Kratos["Ory Kratos Identity Service"]:::external
        ExtProviders["Vulnerability Data Providers (NVD, DebSec, Mitre, GitHub API)"]:::external
        Prometheus["Prometheus Server"]:::external
    end

    %% Core Backend
    subgraph "DevGuard API Server (cmd/devguard)" 
        direction TB
        Echo["Echo HTTP Server & Middleware"]:::internal
        Auth["Auth Middleware (Ory Kratos)"]:::internal
        Controllers["HTTP Controllers"]:::internal
        Services["Core Services"]:::internal
        Repos["Repositories"]:::internal
        Daemons["Background Daemons"]:::internal
        MonitoringEP["Prometheus Metrics Exporter"]:::internal
    end

    DB["PostgreSQL Database"]:::database

    %% Deployment
    subgraph "Kubernetes Cluster (charts/devguard)" 
        direction TB
        APIpod["API Server Pod"]:::internal
        KratosPod["Kratos Pod"]:::external
        DBpod["PostgreSQL Pod"]:::database
    end

    %% Flows
    WebUI -->|HTTP| Echo
    DevGuardCLI -->|HTTP| Echo
    ScannerCLI -->|HTTP| Echo

    Echo -->|middleware| Auth
    Auth -->|gRPC/HTTP| Kratos
    Auth -->|session| Controllers
    Controllers -->|calls| Services
    Services -->|queries| Repos
    Repos -->|SQL| DB

    Daemons -->|ingest| ExtProviders
    Daemons -->|update| DB

    ScannerCLI -->|ingest SBOM & results| Controllers

    MonitoringEP -->|metrics| Prometheus

    %% Deployment links
    APIpod --> Echo
    APIpod --> Daemons
    APIpod --> MonitoringEP
    APIpod --> DB
    APIpod --> Kratos

    KratosPod --> Kratos
    DBpod --> DB

    %% Click Events
    click APIpod "https://github.com/l3montree-dev/devguard/tree/main/charts/devguard"
    click Echo "https://github.com/l3montree-dev/devguard/tree/main/internal/echohttp"
    click Auth "https://github.com/l3montree-dev/devguard/tree/main/internal/auth"
    click Controllers "https://github.com/l3montree-dev/devguard/blob/main/internal/core/*/*_controller.go"
    click Services "https://github.com/l3montree-dev/devguard/blob/main/internal/core/*/*_service.go"
    click Repos "https://github.com/l3montree-dev/devguard/tree/main/internal/database/repositories"
    click DB "https://github.com/l3montree-dev/devguard/tree/main/internal/database/models"
    click Daemons "https://github.com/l3montree-dev/devguard/tree/main/internal/core/daemon"
    click DevGuardCLI "https://github.com/l3montree-dev/devguard/tree/main/cmd/devguard-cli"
    click ScannerCLI "https://github.com/l3montree-dev/devguard/tree/main/cmd/devguard-scanner"
    click Prometheus "https://github.com/l3montree-dev/devguard/tree/main/internal/monitoring"
    click Kratos "https://github.com/l3montree-dev/devguard/blob/main/.kratos"
    click APIpod "https://github.com/l3montree-dev/devguard/tree/main/Dockerfile"
    click ScannerCLI "https://github.com/l3montree-dev/devguard/blob/main/Dockerfile.scanner"
    click APIpod "https://github.com/l3montree-dev/devguard/blob/main/docker-compose.yaml"
    click APIpod "https://github.com/l3montree-dev/devguard/blob/main/config/rbac_model.conf"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#188FA7,stroke-width:2px
    classDef external fill:#C6F6CA,stroke:#2F855A,stroke-width:2px
    classDef client fill:#FEEBC8,stroke:#C05621,stroke-width:2px
    classDef database fill:#E0E7FF,stroke:#4338CA,stroke-width:2px
```
