How sony/stamp works
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.