# greenmaskio/greenmask architecture

> Architecture diagram of the GitHub repository greenmaskio/greenmask, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/greenmaskio/greenmask
- Repository: https://github.com/greenmaskio/greenmask

## Overview

Greenmask is a PostgreSQL logical-backup and data-anonymization utility. Its main workflow is to select database objects, optionally subset related rows, apply configured transformations while dumping, store the resulting backup, and later restore it. The CLI also exposes validation and dump/transformer management. The README documents additional transformation features and storage options; sampled source confirms runtime-context construction and row transformation, but not every command’s internal wiring, so uncertain links are omitted.

Main entry points: [`internal/db/postgres/cmd/dump.go`](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/cmd/dump.go) (Postgres dump), [`internal/db/postgres/context/context.go`](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/context/context.go) (Runtime context), [`cmd/greenmask/cmd/root.go`](https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/root.go) (Command router), [`internal/storages/storager.go`](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/storager.go) (Storage interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_cli_root["Command router<br/>[root.go]"]
  node_dump_cmd["Dump command<br/>[dump.go]"]
  node_restore_cmd["Restore command<br/>[restore.go]"]
  node_validate_cmd["Validate command<br/>[validate.go]"]
  node_dump_admin["Dump management<br/>[list_dumps.go]"]
end

subgraph group_postgres["PostgreSQL runtime"]
  node_pg_dump["Postgres dump<br/>[dump.go]"]
  node_runtime_context["Runtime context<br/>[context.go]"]
  node_subset["Subset planner<br/>[query.go]"]
  node_entry_producer["Entry producer<br/>[entry_producer.go]"]
  node_dump_pipeline["Dump pipeline<br/>[dumpers.go]"]
  node_pgcopy["COPY encoding<br/>[encoder.go]"]
  node_pg_restore["Postgres restore<br/>[restore.go]"]
end

subgraph group_transform["Transformation engine"]
  node_transform_pipeline["Row transformations"]
  node_transformers["Transformer library<br/>[masking.go]"]
  node_transform_registry["Transformer registry<br/>[registry.go]"]
  node_generator["Value generators<br/>[generator.go]"]
end

subgraph group_storage["Backup storage"]
  node_storage_api["Storage interface<br/>[storager.go]"]
  node_storage_builder["Storage selection<br/>[builder.go]"]
  node_local_storage["Directory backend<br/>[directory.go]"]
  node_s3_storage["S3 backend<br/>[s3.go]"]
  node_azure_storage["Azure backend<br/>[azure.go]"]
  node_ssh_storage["SFTP backend<br/>[ssh.go]"]
  node_backup_objects["Backup objects<br/>[domains.go]"]
end

subgraph group_toolkit["Shared data model"]
  node_toolkit_record["Typed records<br/>[record.go]"]
  node_schema_model["Schema model<br/>[database_schema.go]"]
end

node_user(("Operator"))
node_postgres_db[("PostgreSQL")]
node_storage_target[("Storage target")]

node_user -->|"invokes"| node_cli_root
node_cli_root -->|"dispatches"| node_dump_cmd
node_cli_root -->|"dispatches"| node_restore_cmd
node_cli_root -->|"dispatches"| node_validate_cmd
node_cli_root -->|"dispatches"| node_dump_admin
node_dump_cmd -->|"runs dump"| node_pg_dump
node_validate_cmd -->|"builds validation context"| node_runtime_context
node_pg_dump -->|"builds runtime"| node_runtime_context
node_runtime_context -->|"introspects schema"| node_postgres_db
node_runtime_context -->|"plans subset queries"| node_subset
node_runtime_context -->|"collects dump entries"| node_entry_producer
node_entry_producer -->|"reads database objects"| node_postgres_db
node_dump_pipeline -->|"encodes rows"| node_pgcopy
node_transform_pipeline -->|"decodes and encodes"| node_toolkit_record
node_transform_pipeline -->|"applies transforms"| node_transformers
node_transformers -->|"generates values"| node_generator
node_runtime_context -->|"uses transformer definitions"| node_transform_registry
node_pg_dump -->|"streams dump data"| node_dump_pipeline
node_pg_dump -->|"transforms table rows"| node_transform_pipeline
node_pg_dump -->|"selects storage"| node_storage_builder
node_storage_builder -->|"creates backend"| node_storage_api
node_storage_api -->|"implemented by"| node_local_storage
node_storage_api -->|"implemented by"| node_s3_storage
node_storage_api -->|"implemented by"| node_azure_storage
node_storage_api -->|"implemented by"| node_ssh_storage
node_pg_dump -->|"writes backup metadata"| node_backup_objects
node_pg_dump -->|"stores backup"| node_storage_target
node_storage_target -->|"holds objects"| node_backup_objects
node_restore_cmd -->|"runs restore"| node_pg_restore
node_pg_restore -->|"selects storage"| node_storage_builder
node_pg_restore -->|"restores objects"| node_postgres_db
node_runtime_context -->|"builds schema view"| node_schema_model

click node_cli_root "https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/root.go"
click node_dump_cmd "https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/dump/dump.go"
click node_restore_cmd "https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/restore/restore.go"
click node_validate_cmd "https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/validate/validate.go"
click node_dump_admin "https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/list_dumps/list_dumps.go"
click node_pg_dump "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/cmd/dump.go"
click node_runtime_context "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/context/context.go"
click node_subset "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/subset/query.go"
click node_entry_producer "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/entries/entry_producer.go"
click node_dump_pipeline "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/dumpers/dumpers.go"
click node_pgcopy "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/pgcopy/encoder.go"
click node_pg_restore "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/cmd/restore.go"
click node_transform_pipeline "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/dumpers/transformation_pipeline.go"
click node_transformers "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/transformers/masking.go"
click node_transform_registry "https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/transformers/utils/registry.go"
click node_generator "https://github.com/greenmaskio/greenmask/blob/main/internal/generators/generator.go"
click node_storage_api "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/storager.go"
click node_storage_builder "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/builder/builder.go"
click node_local_storage "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/directory/directory.go"
click node_s3_storage "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/s3/s3.go"
click node_azure_storage "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/azure/azure.go"
click node_ssh_storage "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/ssh/ssh.go"
click node_backup_objects "https://github.com/greenmaskio/greenmask/blob/main/internal/storages/domains/domains.go"
click node_toolkit_record "https://github.com/greenmaskio/greenmask/blob/main/pkg/toolkit/record.go"
click node_schema_model "https://github.com/greenmaskio/greenmask/blob/main/pkg/toolkit/database_schema.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_root,node_dump_cmd,node_restore_cmd,node_validate_cmd,node_dump_admin toneBlue
class node_pg_dump,node_runtime_context,node_subset,node_entry_producer,node_dump_pipeline,node_pgcopy,node_pg_restore,node_postgres_db,node_storage_target toneAmber
class node_transform_pipeline,node_transformers,node_transform_registry,node_generator toneMint
class node_storage_api,node_storage_builder,node_local_storage,node_s3_storage,node_azure_storage,node_ssh_storage,node_backup_objects toneRose
class node_toolkit_record,node_schema_model,node_user toneIndigo
```

## Components

### CLI commands

- [Command router](https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/root.go): `cmd/greenmask/cmd/root.go`
- [Dump command](https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/dump/dump.go): `cmd/greenmask/cmd/dump/dump.go`
- [Restore command](https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/restore/restore.go): `cmd/greenmask/cmd/restore/restore.go`
- [Validate command](https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/validate/validate.go): `cmd/greenmask/cmd/validate/validate.go`
- [Dump management](https://github.com/greenmaskio/greenmask/blob/main/cmd/greenmask/cmd/list_dumps/list_dumps.go): `cmd/greenmask/cmd/list_dumps/list_dumps.go`

### PostgreSQL runtime

- [Postgres dump](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/cmd/dump.go): `internal/db/postgres/cmd/dump.go`
- [Runtime context](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/context/context.go): `internal/db/postgres/context/context.go`
- [Subset planner](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/subset/query.go): `internal/db/postgres/subset/query.go`
- [Entry producer](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/entries/entry_producer.go): `internal/db/postgres/entries/entry_producer.go`
- [Dump pipeline](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/dumpers/dumpers.go): `internal/db/postgres/dumpers/dumpers.go`
- [COPY encoding](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/pgcopy/encoder.go): `internal/db/postgres/pgcopy/encoder.go`
- [Postgres restore](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/cmd/restore.go): `internal/db/postgres/cmd/restore.go`

### Transformation engine

- [Row transformations](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/dumpers/transformation_pipeline.go): `internal/db/postgres/dumpers/transformation_pipeline.go`
- [Transformer library](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/transformers/masking.go): `internal/db/postgres/transformers/masking.go`
- [Transformer registry](https://github.com/greenmaskio/greenmask/blob/main/internal/db/postgres/transformers/utils/registry.go): `internal/db/postgres/transformers/utils/registry.go`
- [Value generators](https://github.com/greenmaskio/greenmask/blob/main/internal/generators/generator.go): `internal/generators/generator.go`

### Backup storage

- [Storage interface](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/storager.go): `internal/storages/storager.go`
- [Storage selection](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/builder/builder.go): `internal/storages/builder/builder.go`
- [Directory backend](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/directory/directory.go): `internal/storages/directory/directory.go`
- [S3 backend](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/s3/s3.go): `internal/storages/s3/s3.go`
- [Azure backend](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/azure/azure.go): `internal/storages/azure/azure.go`
- [SFTP backend](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/ssh/ssh.go): `internal/storages/ssh/ssh.go`
- [Backup objects](https://github.com/greenmaskio/greenmask/blob/main/internal/storages/domains/domains.go): `internal/storages/domains/domains.go`

### Shared data model

- [Typed records](https://github.com/greenmaskio/greenmask/blob/main/pkg/toolkit/record.go): `pkg/toolkit/record.go`
- [Schema model](https://github.com/greenmaskio/greenmask/blob/main/pkg/toolkit/database_schema.go): `pkg/toolkit/database_schema.go`

### Other components

- **Operator**
- **PostgreSQL**
- **Storage target**

## Connections

- Operator → Command router: invokes
- Command router → Dump command: dispatches
- Command router → Restore command: dispatches
- Command router → Validate command: dispatches
- Command router → Dump management: dispatches
- Dump command → Postgres dump: runs dump
- Validate command → Runtime context: builds validation context
- Postgres dump → Runtime context: builds runtime
- Runtime context → PostgreSQL: introspects schema
- Runtime context → Subset planner: plans subset queries
- Runtime context → Entry producer: collects dump entries
- Entry producer → PostgreSQL: reads database objects
- Dump pipeline → COPY encoding: encodes rows
- Row transformations → Typed records: decodes and encodes
- Row transformations → Transformer library: applies transforms
- Transformer library → Value generators: generates values
- Runtime context → Transformer registry: uses transformer definitions
- Postgres dump → Dump pipeline: streams dump data
- Postgres dump → Row transformations: transforms table rows
- Postgres dump → Storage selection: selects storage
- Storage selection → Storage interface: creates backend
- Storage interface → Directory backend: implemented by
- Storage interface → S3 backend: implemented by
- Storage interface → Azure backend: implemented by
- Storage interface → SFTP backend: implemented by
- Postgres dump → Backup objects: writes backup metadata
- Postgres dump → Storage target: stores backup
- Storage target → Backup objects: holds objects
- Restore command → Postgres restore: runs restore
- Postgres restore → Storage selection: selects storage
- Postgres restore → PostgreSQL: restores objects
- Runtime context → Schema model: builds schema view