# salesforce/policy_sentry architecture

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

- Interactive diagram: https://gitdiagram.com/salesforce/policy_sentry
- Repository: https://github.com/salesforce/policy_sentry

## Overview

##### Core Project Type and Purpose
- This is a Python-based command line tool (with library usage, Docker support, and even integrations for Terraform) that automates the generation of AWS IAM policies based on resource ARNs and access levels.
- The tool abstracts the complexity of crafting least-privilege IAM policies by reading IAM documentation data (stored in YAML files under “shared/data”) and providing functionality via various command modules.

##### Main Components
A. CLI & User Interface:
- Entry point(s) found in policy_sentry/bin (e.g., cli.py) where user commands such as “create-template”, “write-policy”, “query”, and “initialize” are parsed.
- Integration points for different interfaces such as the native Python CLI, Docker entrypoints (in “utils/entrypoint.sh” and Dockerfile), and even Homebrew commands.

B. Command & Control Layer:
- Mapping from CLI to these command modules.

C. Core Business Logic & Processing Engine:
- “analysis”, “querying”, and “writing” modules within policy_sentry. These form the core engine for processing user inputs:
– The Analysis component is responsible for interpreting input ARNs and expanding them into actionable sets.
– The Querying component provides methods to retrieve details from the IAM database (using data files provided under “shared/data”).
– The Writing component uses policy templates and logic to generate the final IAM policy JSON output.
- Incorporate the “util” modules that facilitate text processing, file handling, and access level management.

D. Data Management & Configuration:
- Configuration files (like pyproject.toml, .readthedocs.yml, and various GitHub workflows) that support building, testing, and documentation.

E. Testing and Documentation:
- “test” directory as an ancillary component that validates all functionality using unit and integration tests.
- That documentation is built via MkDocs (mkdocs.yml and docs/) and ReadTheDocs integration.

F. External Integration / Distribution Layers:
- Docker: Show the Dockerfile that builds the container image and related utilities in the “utils” directory.
- Homebrew & PyPI: Indicate that distribution mechanisms (e.g., Homebrew formula and pip installation) wrap around the core functionality.
- Terraform Module: Include the separate “terraform_module” directory, which demonstrates how Policy Sentry’s output is integrated into infrastructure as code use cases.

##### Relationships and Data Flow
- From the CLI, the command layer directs requests to the core engine. The engine consults the IAM data configuration (and any overrides) to compute relevant IAM actions.
- Finally, the engine outputs a JSON-formatted IAM policy for consumption.
- Also, illustrate the feedback loop for queries (e.g., where the “query” command reads from the IAM database) and note the modular design that separates these concerns.

##### Architectural Patterns and Design Principles
- A layered architecture where:
– The CLI/Interface layer manages I/O and user commands.
– The Command module maps these inputs to core business logic.
– The Core Engine handles the complex processing – applying a domain-specific abstraction (i.e., the logic for IAM policy generation).
– The Data layer segregates static resources, configuration, and external integrations.
- Separation of concerns, where each module such as analysis, querying, and writing is self-contained, improving testability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    UI["User Input"]

    %% CLI & User Interface Subgraph
    subgraph "CLI & User Interface"
        CLI["CLI Interface (policy_sentry/bin/cli.py)"]
        Version["CLI Version Info (policy_sentry/bin/version.py)"]
        Entrypoint["Docker Entrypoint (utils/entrypoint.sh)"]
        DockerF["Dockerfile"]
    end

    %% Command & Control Layer Subgraph
    subgraph "Command & Control Layer"
        Cmd["Command Modules (policy_sentry/command/)"]
    end

    %% Core Business Logic & Processing Engine Subgraph
    subgraph "Core Business Logic & Processing Engine"
        Analysis["Analysis Module (policy_sentry/analysis/)"]
        Querying["Querying Module (policy_sentry/querying/)"]
        Writing["Writing Module (policy_sentry/writing/)"]
        Util["Utility Modules (policy_sentry/util/)"]
    end

    %% Data Management & Configuration Subgraph
    subgraph "Data Management & Configuration"
        IAMData["IAM Data Store (policy_sentry/shared/data/)"]
        Config["Configuration Files (pyproject.toml, .readthedocs.yml, .github/workflows/)"]
    end

    %% Output Generation
    Output["IAM Policy JSON Output"]

    %% Testing & Documentation Subgraph
    subgraph "Testing & Documentation"
        TestSuite["Test Suite (test/)"]
        Docs["Documentation (docs/ & mkdocs.yml)"]
    end

    %% External Integration / Distribution Layers Subgraph
    subgraph "External Integration"
        DockerDist["Docker Distribution (Dockerfile, utils/entrypoint.sh)"]
        Homebrew["Homebrew Distribution (HomebrewFormula/policy_sentry.rb)"]
        Terraform["Terraform Integration (terraform_module/)"]
    end

    %% Flow Connections
    UI -->|"initiates"| CLI
    CLI -->|"triggers"| Cmd
    Cmd -->|"orchestrates"| Analysis
    Cmd -->|"orchestrates"| Querying
    Cmd -->|"orchestrates"| Writing
    Cmd -->|"uses"| Util

    Analysis -->|"consults"| IAMData
    Querying -->|"retrieves from"| IAMData
    Writing -->|"reads config from"| Config
    Util -->|"assists"| Analysis
    Util -->|"assists"| Writing

    Analysis -->|"produces"| Output
    Querying -->|"supports"| Output
    Writing -->|"produces"| Output

    Config -->|"feeds"| Analysis
    Config -->|"feeds"| Querying
    Config -->|"feeds"| Writing

    Output -->|"validated by"| TestSuite
    Output -->|"documented in"| Docs

    Output -->|"distributed via"| DockerDist
    Output -->|"distributed via"| Homebrew
    Output -->|"distributed via"| Terraform

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef command fill:#C3F584,stroke:#6AA121,stroke-width:2px;
    classDef engine fill:#FFF79A,stroke:#D4AC0D,stroke-width:2px;
    classDef data fill:#D6DBDF,stroke:#566573,stroke-width:2px;
    classDef output fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef test fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#C0392B,stroke-width:2px;

    class CLI,Version,Entrypoint,DockerF cli;
    class Cmd command;
    class Analysis,Querying,Writing,Util engine;
    class IAMData,Config data;
    class Output output;
    class TestSuite,Docs test;
    class DockerDist,Homebrew,Terraform external;

    %% Click Events
    click CLI "https://github.com/salesforce/policy_sentry/blob/master/policy_sentry/bin/cli.py"
    click Version "https://github.com/salesforce/policy_sentry/blob/master/policy_sentry/bin/version.py"
    click Entrypoint "https://github.com/salesforce/policy_sentry/blob/master/utils/entrypoint.sh"
    click DockerF "https://github.com/salesforce/policy_sentry/tree/master/Dockerfile"
    click Cmd "https://github.com/salesforce/policy_sentry/tree/master/policy_sentry/command/"
    click Analysis "https://github.com/salesforce/policy_sentry/tree/master/policy_sentry/analysis/"
    click Querying "https://github.com/salesforce/policy_sentry/tree/master/policy_sentry/querying/"
    click Writing "https://github.com/salesforce/policy_sentry/tree/master/policy_sentry/writing/"
    click Util "https://github.com/salesforce/policy_sentry/tree/master/policy_sentry/util/"
    click IAMData "https://github.com/salesforce/policy_sentry/tree/master/policy_sentry/shared/data/"
    click Config "https://github.com/salesforce/policy_sentry/blob/master/pyproject.toml"
    click TestSuite "https://github.com/salesforce/policy_sentry/tree/master/test/"
    click Docs "https://github.com/salesforce/policy_sentry/tree/master/docs/"
    click Homebrew "https://github.com/salesforce/policy_sentry/blob/master/HomebrewFormula/policy_sentry.rb"
    click Terraform "https://github.com/salesforce/policy_sentry/tree/master/terraform_module/"
    click DockerDist "https://github.com/salesforce/policy_sentry/tree/master/Dockerfile"
```
