# sony/stamp architecture

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

- Interactive diagram: https://gitdiagram.com/sony/stamp
- Repository: https://github.com/sony/stamp

## Overview

##### Main Components
- Frontend Web UI: Located under apps/web-ui. It uses Next.js (see next.config.js, custom server code, API routes under apps/web-ui/src/app/api, and client components) and provides the user interface for submitting and approving requests.
- Backend Workflow Engine (Hub): Found within packages/hub and its workflows. This is the business logic layer where approval flows, processing of requests, authentication/authorization, and orchestration reside.
- Plugins: In the plugins folder you find several integration adapters (for DynamoDB, ephemeral databases/identity, Slack integrations, and eventbridge-scheduler). They are used to extend Stamp’s capabilities in communicating with external systems.
- Shared Libraries/Packages: The packages directory contains libraries such as config, logger, types, option, and plugin-router. These provide common functionality and interfaces to standardize behavior across different parts of the system.
- External Services: The README and configuration files indicate that Stamp is designed to work with AWS services – DynamoDB for data persistence, Cognito for authentication, and AWS container services like ECS/AppRunner for deployment. Other integrations include Slack for approvals and notifications.

##### Relationships and Interactions
- The Web UI (frontend) communicates with backend API endpoints (Next.js API routes in apps/web-ui/src/app/api). This layer handles tasks like authentication (using Cognito) and initiating approval requests.
- Once an approval request is submitted, the backend (hub/workflows) takes over. It orchestrates the approval flow logic, validates requests, and calls the appropriate workflows defined in the catalogs.
- The workflows interact with external systems (AWS services, Slack) via the plugins. For example, a plugin (e.g., plugins/slack) manages Slack notifications or approval submissions. Similarly, plugins for DynamoDB provide the persistence layer.
- The shared packages (config, logger, types) are used throughout for consistency – they define interfaces, common configurations, and logging/error handling.
- A custom server component in apps/web-ui/custom-server (with code in TypeScript files like dynamodbApp.ts, index.ts, stampServer.ts) may tie together local development with production-like API behavior.

##### Architectural Patterns and Design Principles
- Modular/Plug-in Architecture: The project is broken up into modular pieces (catalogs, plugins, packages). Each integration (e.g., IAM Identity Center, IAM Role, Slack) is isolated so the system can be easily extended.
- Separation of Concerns: There is a clear boundary between the frontend (web UI), the core workflow engine (hub in packages), and the external integrations (plugins).
- Monorepo Structure: Using tools like lerna (as indicated by lerna.json), the project maintains a single repository for multiple modules, easing dependency management and versioning.
- API-First and Server-Side Processing: The Next.js API routes drive the interaction between the client and the processing engine, with server-actions and middleware files coordinating backend behavior.

##### Technologies, Frameworks, and External Services
- Next.js (apps/web-ui) for the frontend and serverless API endpoints.
- TypeScript for full type safety across the project.
- AWS Services: DynamoDB, Cognito, and container services (ECS/AppRunner) for production deployment.
- Slack (via plugins/slack) for API-based approval actions.
- AWS EventBridge Scheduler (plugins/eventbridge-scheduler) to trigger scheduled actions.
- Testing and linting tools shown by Vitest, ESLint, and Prettier configurations.

##### Elements

- Out the high-level structure starting at the top with the Frontend (Web UI).
- Workflow Engine to the Catalogs, which host the integration logic (IAM Identity Center catalog, IAM Role catalog).
- Attach the Plugins module next, and list each relevant adapter for DynamoDB, Slack, EventBridge, and ephemeral solutions.
- Don’t forget to include the custom server elements (found under apps/web-ui/custom-server) as part of the API layer, if they help mediate between the UI and the backend processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Frontend Web UI"):::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API("API Endpoints"):::api
        CS("Custom Server"):::api
    end

    %% Workflow Orchestrator
    subgraph "Workflow Orchestrator"
        WE("Workflow Engine (Hub)"):::workflow
        subgraph "Catalogs"
            CIC("IAM Identity Center Catalog"):::workflow
            RC("IAM Role Catalog"):::workflow
        end
        subgraph "Plugins"
            DDBP("DynamoDB Persistence"):::plugin
            DDBI("DynamoDB Identity Integration"):::plugin
            EPI("Ephemeral Identity Integration"):::plugin
            EPDB("Ephemeral Database"):::plugin
            EBSched("EventBridge Scheduler"):::plugin
            SI("Slack Integration"):::plugin
        end
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        ConfigLib("Config Library"):::shared
        LoggingLib("Logging Library"):::shared
        OptionsUtil("Options/Utilities"):::shared
        PluginRouter("Plugin Router"):::shared
        TypeDefs("Type Definitions"):::shared
    end

    %% External Services
    subgraph "External Services"
        AWS_DDB("AWS DynamoDB"):::external
        AWS_COG("AWS Cognito"):::external
        SlackExt("Slack API"):::external
    end

    %% Connections
    FE -->|"submitsRequest"| API
    API -->|"routesTo"| CS
    CS -->|"triggers"| WE

    WE -->|"selectsCatalog"| CIC
    WE -->|"selectsCatalog"| RC

    WE -->|"invokes"| DDBP
    WE -->|"invokes"| DDBI
    WE -->|"invokes"| EPI
    WE -->|"invokes"| EPDB
    WE -->|"invokes"| EBSched
    WE -->|"invokes"| SI

    DDBP -->|"storesData"| AWS_DDB
    DDBI -->|"verifiesIdentity"| AWS_COG
    SI -->|"sendsNotification"| SlackExt

    %% Shared Libraries dependencies (dotted lines)
    ConfigLib -.-> API
    LoggingLib -.-> API
    OptionsUtil -.-> API
    PluginRouter -.-> WE
    TypeDefs -.-> API
    TypeDefs -.-> WE

    %% Click Events
    click FE "https://github.com/sony/stamp/tree/main/apps/web-ui"
    click API "https://github.com/sony/stamp/tree/main/apps/web-ui/src/app/api"
    click CS "https://github.com/sony/stamp/tree/main/apps/web-ui/custom-server"
    click WE "https://github.com/sony/stamp/tree/main/packages/hub"
    click CIC "https://github.com/sony/stamp/tree/main/catalogs/iam-idc"
    click RC "https://github.com/sony/stamp/tree/main/catalogs/iam-role"
    click DDBP "https://github.com/sony/stamp/tree/main/plugins/dynamodb-db"
    click DDBI "https://github.com/sony/stamp/tree/main/plugins/dynamodb-identity"
    click EPI "https://github.com/sony/stamp/tree/main/plugins/ephemeral-identity"
    click EPDB "https://github.com/sony/stamp/tree/main/plugins/ephemeral-db"
    click EBSched "https://github.com/sony/stamp/tree/main/plugins/eventbridge-scheduler"
    click SI "https://github.com/sony/stamp/tree/main/plugins/slack"
    click ConfigLib "https://github.com/sony/stamp/tree/main/packages/config"
    click LoggingLib "https://github.com/sony/stamp/tree/main/packages/logger"
    click OptionsUtil "https://github.com/sony/stamp/tree/main/packages/option"
    click PluginRouter "https://github.com/sony/stamp/tree/main/packages/plugin-router"
    click TypeDefs "https://github.com/sony/stamp/tree/main/packages/types"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef workflow fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef plugin fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
