# jbcongdon/platform architecture

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

- Interactive diagram: https://gitdiagram.com/jbcongdon/platform
- Repository: https://github.com/jbcongdon/platform

## Overview

##### Project type and purpose
- This is a backend platform monorepo (“OpenTDF”) that provides a modular set of gRPC‐based microservices, a native Go SDK, CLI tools, shared libraries, protobuf definitions and example clients. Its purpose is to enforce attribute‐based access control (ABAC) on encrypted data via a set of services (authorization, entity‐resolution, policy, key‐access (KAS), logging) and an OIDC IdP (Keycloak) for authentication.

##### File structure
- Top‐level modules:
- service/ – the main OpenTDF service and sub‐services (authorization, entityresolution, kas, logger, health)
- sdk/       – the native Go SDK and generated service SDKs
- lib/       – shared libraries (crypto, flattening, fixtures)
- protocol/  – protobuf definitions and generated Go stubs (gRPC + HTTP‐gateway)
- examples/  – sample CLI programs demonstrating encrypt/decrypt, metrics, authorization
- docker-compose.yaml, Dockerfile, .github/ – orchestration and CI/CD configuration
- Notice the microservice pattern: each domain (policy, authorization, entityresolution, kas) has its own proto, its own Go implementation and its own test suite.
- Configuration YAMLs (opentdf-*.yaml) define service endpoints, database connections, Keycloak OIDC settings.
- buf.yaml + buf.gen.* manage protobuf code generation (gRPC + OpenAPI).

##### README for additional insights
- Core entrypoint: the “service” binary (service/cmd/start.go)
- Dependencies: Go, Docker Compose, Buf, Keycloak
- Quickstart shows: Key Generation → Docker Compose up (Postgres, Keycloak, service, KAS) → Provision Keycloak → Run service → Use SDK/CLI to encrypt/decrypt.
- The README calls out ABAC (PDP/PEP), OIDC, and policy schemas (ERD) as central concepts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        SDK["Go SDK"]:::client
        CLI["CLI Examples"]:::client
        REST["HTTP/REST Clients (OpenAPI)"]:::client
    end

    %% External IdP
    KC["Keycloak (OIDC IdP)"]:::external

    %% Microservices
    subgraph "Microservices"
        AuthZ["Authorization Service\n(gRPC:50052 / HTTP:9092)"]:::service
        ER["Entity Resolution Service\n(gRPC:50053 / HTTP:9093)"]:::service
        Policy["Policy Service (PDP)\n(gRPC:50051 / HTTP:9090)"]:::service
        KAS["Key Access Service (KAS)\n(gRPC:50054 / HTTP:9094)"]:::service
        Log["Logging Service (Audit)\n(gRPC:50055 / HTTP:9095)"]:::service
        Health["Health & Metrics Service\n(gRPC:50056 / HTTP:9096)"]:::service
    end

    %% Datastores
    PG["PostgreSQL"]:::db

    %% Shared Libraries
    subgraph "Shared Libraries"
        Crypto["ocrypto"]:::lib
        Flatten["flattening"]:::lib
        Fixtures["fixtures"]:::lib
    end

    %% Code Generation and Config
    Protocol["Protobuf Definitions & Stubs"]:::codegen
    Config["Configuration YAMLs"]:::config
    Docker["Docker Compose"]:::config
    Entrypoint["Main Service Entrypoint\nservice/cmd/start.go"]:::entry

    %% Client to Services
    SDK -->|gRPC/HTTP| AuthZ
    SDK -->|gRPC/HTTP| ER
    SDK -->|gRPC/HTTP| Policy
    SDK -->|gRPC/HTTP| KAS
    SDK -->|gRPC/HTTP| Log
    SDK -->|gRPC/HTTP| Health

    CLI -->|gRPC/HTTP| AuthZ
    CLI -->|gRPC/HTTP| ER
    CLI -->|gRPC/HTTP| Policy
    CLI -->|gRPC/HTTP| KAS
    CLI -->|gRPC/HTTP| Log
    CLI -->|gRPC/HTTP| Health

    REST -->|HTTP/REST| AuthZ
    REST -->|HTTP/REST| ER
    REST -->|HTTP/REST| Policy
    REST -->|HTTP/REST| KAS
    REST -->|HTTP/REST| Log
    REST -->|HTTP/REST| Health

    %% Service interactions
    AuthZ -->|PDP Calls| Policy
    AuthZ -->|Audit Events| Log
    ER -->|Audit Events| Log
    Policy -->|Audit Events| Log
    KAS -->|Audit Events| Log
    Health -->|Audit Events| Log

    %% Services to Datastore
    Policy -->|SQL Queries| PG

    %% Services to IdP
    AuthZ -->|OIDC Token Introspection| KC
    ER -->|OIDC Discovery| KC
    Policy -->|OIDC Introspection| KC
    KAS -->|OIDC Introspection| KC
    Log -->|OIDC Introspection| KC
    Health -->|OIDC Introspection| KC

    %% Shared Lib usage
    AuthZ --> Crypto
    ER --> Crypto
    Policy --> Crypto
    KAS --> Crypto
    Log --> Crypto
    Health --> Crypto

    AuthZ --> Flatten
    ER --> Flatten
    Policy --> Flatten
    KAS --> Flatten

    AuthZ --> Fixtures
    ER --> Fixtures
    Policy --> Fixtures

    %% Codegen & Config
    Protocol --> AuthZ
    Protocol --> ER
    Protocol --> Policy
    Protocol --> KAS
    Protocol --> Log
    Protocol --> Health

    Config -.-> AuthZ
    Config -.-> ER
    Config -.-> Policy
    Config -.-> KAS
    Config -.-> Log
    Config -.-> Health

    Docker -.-> AuthZ
    Docker -.-> ER
    Docker -.-> Policy
    Docker -.-> KAS
    Docker -.-> Log
    Docker -.-> Health

    Entrypoint --> AuthZ
    Entrypoint --> ER
    Entrypoint --> Policy
    Entrypoint --> KAS
    Entrypoint --> Log
    Entrypoint --> Health

    %% Click Events
    click AuthZ "https://github.com/jbcongdon/platform/blob/main/service/authorization/authorization.go"
    click AuthZ "https://github.com/jbcongdon/platform/blob/main/service/authorization/authorization.proto"
    click ER "https://github.com/jbcongdon/platform/blob/main/service/entityresolution/entityresolution.go"
    click ER "https://github.com/jbcongdon/platform/blob/main/service/entityresolution/entity_resolution.proto"
    click Policy "https://github.com/jbcongdon/platform/tree/main/service/policy/"
    click Policy "https://github.com/jbcongdon/platform/blob/main/service/policy/objects.proto"
    click KAS "https://github.com/jbcongdon/platform/blob/main/service/kas/kas.go"
    click KAS "https://github.com/jbcongdon/platform/blob/main/service/kas/kas.proto"
    click KAS "https://github.com/jbcongdon/platform/tree/main/service/kas/access/"
    click Log "https://github.com/jbcongdon/platform/blob/main/service/logger/logger.go"
    click Log "https://github.com/jbcongdon/platform/tree/main/service/logger/audit/"
    click Health "https://github.com/jbcongdon/platform/blob/main/service/health/health.go"
    click Crypto "https://github.com/jbcongdon/platform/tree/main/lib/ocrypto/"
    click Flatten "https://github.com/jbcongdon/platform/blob/main/lib/flattening/flatten.go"
    click Fixtures "https://github.com/jbcongdon/platform/tree/main/lib/fixtures/"
    click SDK "https://github.com/jbcongdon/platform/tree/main/sdk/"
    click CLI "https://github.com/jbcongdon/platform/tree/main/examples/cmd/"
    click Protocol "https://github.com/jbcongdon/platform/tree/main/protocol/go/"
    click Policy "https://github.com/jbcongdon/platform/tree/main/service/policy/db/migrations/"
    click Policy "https://github.com/jbcongdon/platform/blob/main/service/policy/db/models.go"
    click Config "https://github.com/jbcongdon/platform/blob/main/opentdf-*.yaml"
    click Docker "https://github.com/jbcongdon/platform/blob/main/docker-compose.yaml"
    click Entrypoint "https://github.com/jbcongdon/platform/blob/main/service/cmd/start.go"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#4A90E2,stroke-width:1px;
    classDef service fill:#E6F9E6,stroke:#2ECC71,stroke-width:1px;
    classDef db fill:#FFE6CC,stroke:#E67E22,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#95A5A6,stroke-width:1px;
    classDef lib fill:#F5E6FF,stroke:#9B59B6,stroke-width:1px;
    classDef codegen fill:#FFF5E6,stroke:#F39C12,stroke-width:1px,stroke-dasharray: 5 5;
    classDef config fill:#F0F0F0,stroke:#7F8C8D,stroke-width:1px,stroke-dasharray: 2 2;
    classDef entry fill:#E8F6F3,stroke:#1ABC9C,stroke-width:1px;
```
