# getprobo/probo architecture

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

- Interactive diagram: https://gitdiagram.com/getprobo/probo
- Repository: https://github.com/getprobo/probo

## Overview

##### Project Type and Purpose
- Probo is a full-stack, open-source compliance platform. It comprises:
- Two Single-Page Applications (SPAs): “console” for authenticated users, and “trust” for public trust center access.
- A monolithic Go backend exposing two GraphQL API endpoints (/console/v1 and /trust/v1).
- A PostgreSQL database, observability stack (Prometheus, Grafana, Loki, Tempo), and ancillary services (cert-manager, mailer, file manager).

##### File-Structure Highlights and Architectural Patterns
- apps/console & apps/trust: React+TypeScript SPAs, each built with Vite and Relay.
- pkg/server/api/console/v1 & pkg/server/api/trust/v1: GraphQL schema, resolvers, HTTP handlers.
- pkg/probo & pkg/trust & pkg/coredata: Service layer and data-access layer (domain logic, migrations).
- compose/: Docker Compose definitions for infrastructure.
- pkg/connector, pkg/certmanager, pkg/mailer, pkg/filemanager, etc.: Modular helper services.

##### API Layer Overview
- Two GraphQL endpoints:
- Console API (/console/v1) handles user/organization management, controls, audits, documents, tasks, snapshots, vendor and trust-center operations.
- Trust API (/trust/v1) serves the public trust center: limited view of audits, documents, NDA workflows, and vendor status.
- HTTP Server (pkg/server/server.go) routes traffic to the appropriate GraphQL handler or static file handler (statichandler for SPAs).
- Resolvers delegate to application services in pkg/probo or pkg/trust, which encapsulate business logic.
- Domain services use pkg/coredata for ORM-style entities and run SQL migrations via embedded migration files.
- Authentication & Authorization:
- pkg/auth, pkg/authz implement session management, JWTs, and permission checks.
- Console API enforces organization-scoped RBAC, Trust API uses token-based trust auth.

##### Main Components and Interactions
[Frontend]
- Console SPA (React/Relay) ⇄ Console GraphQL endpoint
- Trust SPA (React/Relay) ⇄ Trust GraphQL endpoint
[API Layer]
- HTTP Router → GraphQL handlers (gqlgen) → Resolvers
- Resolvers → Application services (pkg/probo / pkg/trust)
[Service Layer]
- Application services → Domain logic & validation (pkg/coredata, pkg/filevalidation)
- Auxiliary services: connector (OAuth2), certmanager (Let’s Encrypt), mailer (emails via packages/emails), html2pdf, watermarkpdf
[Data Layer]
- Services → PostgreSQL (via pkg/coredata migrations)
- File storage (attachments) via S3 or local blob store configured in cfg/*.yaml
[Infrastructure & Observability]
- Docker Compose orchestrates: PostgreSQL, Pebble (ACME testing CA), Prometheus, Grafana, Tempo
- OpenTelemetry instrumentation in Go code (pkg/server/graphql/tracing.go)

##### Architectural Patterns & Design Principles
- Monolithic, modular service design: single binary (“probod”) serving multiple APIs.
- Layered architecture: HTTP → GraphQL → Resolvers → Services → Data access.
- Schema-first GraphQL (gqlgen) with code generation for type safety.
- Domain-driven modules in pkg/*, helper libraries in packages/*, UI component library in packages/ui.
- Containerized local development and infrastructure via Docker Compose.

##### API Layer Focus
- /console/graphql → gqlgen Console resolver set
- /trust/graphql → gqlgen Trust resolver set
- How generated GraphQL types (pkg/server/api/*/types) map to domain entities (pkg/coredata).
- Middleware chain: OpenTelemetry traces → AuthN/AuthZ → Logging → Rate-Limiting → GraphQL execution.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        ConsoleApp["Console SPA\n(React/Relay)"]:::frontend
        TrustApp["Trust SPA\n(React/Relay)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        HTTPServer["HTTP Server\n(pkg/server/server.go)"]:::backend
        APIAGG["API Aggregator\n(pkg/server/api/api.go)"]:::backend
        StaticHandler["Static File Handler\n(pkg/server/statichandler/statichandler.go)"]:::backend
        subgraph "GraphQL Middleware"
            direction TB
            GraphQLMiddleware["Middleware & Tracing\n(pkg/server/graphql)"]:::backend
            Recovery["Recovery Handler\n(pkg/server/graphql/recovery.go)"]:::backend
        end
        subgraph "GraphQL Endpoints"
            direction TB
            ConsoleAPI["Console GraphQL API\n/console/v1"]:::api
            TrustAPI["Trust GraphQL API\n/trust/v1"]:::api
        end
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ConsoleServices["Console Services\n(pkg/probo)"]:::service
        TrustServices["Trust Services\n(pkg/trust)"]:::service
        AuthService["Auth Service\n(pkg/auth/service.go)"]:::service
        AuthzService["Authorization Service\n(pkg/authz/service.go)"]:::service
        FileValidation["File Validation\n(pkg/filevalidation/validator.go)"]:::service
        GID["ID Generation\n(pkg/gid)"]:::service
        SecureCookie["Secure Cookie\n(pkg/securecookie/securecookie.go)"]:::service
        StatelessToken["Stateless Token\n(pkg/statelesstoken/token.go)"]:::service
        ConfigLoader["Config Loader\n(cmd/probod/api_config.go)"]:::service
        subgraph "Auxiliary Services"
            direction TB
            ConnectorSvc["Connector Service\n(pkg/connector)"]:::aux
            CertMgr["Cert Manager\n(pkg/certmanager)"]:::aux
            Mailer["Mailer Service\n(pkg/mailer/mailer.go)"]:::aux
            FileMgr["File Manager\n(pkg/filemanager/service.go)"]:::aux
            HTML2PDF["HTML→PDF Converter\n(pkg/html2pdf/converter.go)"]:::aux
            Watermark["PDF Watermark\n(pkg/watermarkpdf/watermarkpdf.go)"]:::aux
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["PostgreSQL"]:::database
        CoreData["Domain Entities\n(pkg/coredata/*.go)"]:::database
        Migrations["SQL Migrations\n(pkg/coredata/migrations)"]:::database
        BlobStorage["Blob Storage\n(S3/local)"]:::database
    end

    %% Observability & Infrastructure
    subgraph "Observability"
        direction TB
        Prometheus["Prometheus"]:::infra
        Grafana["Grafana"]:::infra
        Loki["Loki"]:::infra
        Tempo["Tempo"]:::infra
    end

    subgraph "Infrastructure"
        direction TB
        DockerCompose["Docker Compose\n(compose/)"]:::infra
        PromConfig["Prometheus Config\n(compose/prometheus/prometheus.yaml)"]:::infra
        GrafanaProv["Grafana Provisioning\n(compose/grafana/provisioning/datasources/datasources.yaml)"]:::infra
        TempoCfg["Tempo Config\n(compose/tempo/tempo.yaml)"]:::infra
        PostgresInit["Postgres Init Script\n(compose/postgres/01_probod.sh)"]:::infra
    end

    %% Connections: Frontend → API
    ConsoleApp -->|"Relay fetch"| HTTPServer
    TrustApp -->|"Relay fetch"| HTTPServer

    %% HTTP Server routing
    HTTPServer -->|"mount APIs"| APIAGG
    HTTPServer -->|"serve static"| StaticHandler
    APIAGG -->|"POST /console/graphql"| ConsoleAPI
    APIAGG -->|"POST /trust/graphql"| TrustAPI

    %% Middleware to Endpoints
    ConsoleAPI -->|"middleware stack"| GraphQLMiddleware
    TrustAPI -->|"middleware stack"| GraphQLMiddleware
    GraphQLMiddleware --> Recovery

    %% Middleware services
    GraphQLMiddleware --> AuthService
    GraphQLMiddleware --> AuthzService
    GraphQLMiddleware --> Tempo

    %% Endpoints to Services
    ConsoleAPI -->|"resolver calls"| ConsoleServices
    TrustAPI -->|"resolver calls"| TrustServices

    %% Services to data and helpers
    ConsoleServices --> CoreData
    TrustServices --> CoreData
    ConsoleServices --> Postgres
    TrustServices --> Postgres
    ConsoleServices --> BlobStorage
    TrustServices --> BlobStorage
    ConsoleServices --> FileValidation
    ConsoleServices --> ConnectorSvc
    ConsoleServices --> CertMgr
    ConsoleServices --> Mailer
    ConsoleServices --> FileMgr
    ConsoleServices --> HTML2PDF
    ConsoleServices --> Watermark
    ConsoleServices --> GID
    ConsoleServices --> SecureCookie
    TrustServices --> StatelessToken
    TrustServices --> ConfigLoader

    %% Docker Compose orchestration
    DockerCompose --> Postgres
    DockerCompose --> Prometheus
    DockerCompose --> Grafana
    DockerCompose --> Loki
    DockerCompose --> Tempo

    %% Class Definitions
    classDef frontend fill:#EFEFFF,stroke:#009,stroke-width:1px
    classDef backend fill:#FFEFEF,stroke:#900,stroke-width:1px
    classDef api fill:#FFF5E6,stroke:#995500,stroke-width:1px,shape:hexagon
    classDef service fill:#E8FFE8,stroke:#090,stroke-width:1px
    classDef aux fill:#F0F8FF,stroke:#06F,stroke-width:1px,shape:oval
    classDef database fill:#FFF0F5,stroke:#C04,stroke-width:1px,shape:cylinder
    classDef infra fill:#F5F5F5,stroke:#555,stroke-width:1px,shape:cloud

    %% Click Events
    click ConsoleApp "https://github.com/getprobo/probo/tree/main/apps/console"
    click TrustApp "https://github.com/getprobo/probo/tree/main/apps/trust"
    click HTTPServer "https://github.com/getprobo/probo/blob/main/pkg/server/server.go"
    click APIAGG "https://github.com/getprobo/probo/blob/main/pkg/server/api/api.go"
    click StaticHandler "https://github.com/getprobo/probo/blob/main/pkg/server/statichandler/statichandler.go"
    click GraphQLMiddleware "https://github.com/getprobo/probo/tree/main/pkg/server/graphql"
    click Recovery "https://github.com/getprobo/probo/blob/main/pkg/server/graphql/recovery.go"
    click ConsoleAPI "https://github.com/getprobo/probo/tree/main/pkg/server/api/console/v1"
    click TrustAPI "https://github.com/getprobo/probo/tree/main/pkg/server/api/trust/v1"
    click AuthService "https://github.com/getprobo/probo/blob/main/pkg/auth/service.go"
    click AuthzService "https://github.com/getprobo/probo/blob/main/pkg/authz/service.go"
    click ConsoleServices "https://github.com/getprobo/probo/tree/main/pkg/probo/"
    click TrustServices "https://github.com/getprobo/probo/tree/main/pkg/trust/"
    click CoreData "https://github.com/getprobo/probo/tree/main/pkg/coredata/"
    click Migrations "https://github.com/getprobo/probo/tree/main/pkg/coredata/migrations"
    click ConnectorSvc "https://github.com/getprobo/probo/tree/main/pkg/connector/"
    click CertMgr "https://github.com/getprobo/probo/tree/main/pkg/certmanager/"
    click Mailer "https://github.com/getprobo/probo/blob/main/pkg/mailer/mailer.go"
    click FileMgr "https://github.com/getprobo/probo/blob/main/pkg/filemanager/service.go"
    click FileValidation "https://github.com/getprobo/probo/blob/main/pkg/filevalidation/validator.go"
    click HTML2PDF "https://github.com/getprobo/probo/blob/main/pkg/html2pdf/converter.go"
    click Watermark "https://github.com/getprobo/probo/blob/main/pkg/watermarkpdf/watermarkpdf.go"
    click GID "https://github.com/getprobo/probo/tree/main/pkg/gid/"
    click SecureCookie "https://github.com/getprobo/probo/blob/main/pkg/securecookie/securecookie.go"
    click StatelessToken "https://github.com/getprobo/probo/blob/main/pkg/statelesstoken/token.go"
    click ConfigLoader "https://github.com/getprobo/probo/blob/main/cmd/probod/api_config.go"
    click DockerCompose "https://github.com/getprobo/probo/tree/main/compose/"
    click PromConfig "https://github.com/getprobo/probo/blob/main/compose/prometheus/prometheus.yaml"
    click GrafanaProv "https://github.com/getprobo/probo/blob/main/compose/grafana/provisioning/datasources/datasources.yaml"
    click TempoCfg "https://github.com/getprobo/probo/blob/main/compose/tempo/tempo.yaml"
    click PostgresInit "https://github.com/getprobo/probo/blob/main/compose/postgres/01_probod.sh"
```
