Actions Tools App

actionstools-app is the backend for the CRM UI components used by the internal admin (IA) and service desk: notes, file attachments, tasks, comments, notifications, the supplier activity stream and the global settings (task statuses, email templates, folders). The UI components own the presentation; this service owns storage, permissions, notifications and the counters behind the task grid.

The 30-second model

  • Two Lambda functions, one code base. ApiFunction serves HTTP through API Gateway; WorkerFunction runs background work. Both are defined in template.yaml and deployed by AWS SAM as one CloudFormation stack per environment (actionstools-prod, actionstools-stage).

  • Flask + flask-restx. run.py builds the Flask app, lambda_handlers.py adapts it to Lambda with apig-wsgi. Most endpoints are flask-restx namespaces (they show up in Swagger); a few are plain Flask blueprints.

  • DynamoDB for everything. Eight em_actions_* tables, accessed through flask-dynamo and the CRUD services of the internal pyb_flask_utils library.

  • Background work is a Lambda invoke. Functions decorated with @async_task are sent to the Worker as an asynchronous invocation. The Worker also consumes the tasks table stream (to keep grid counters current) and a 4-day cleanup schedule.

  • Secrets live in Secrets Manager. secrets_loader.py copies the actionstools/<env> secret into os.environ at cold start, before any module reads configuration.

  CRM UI ──X-Session-Token──► API Gateway (REST, CORS) ──► ApiFunction (Flask)
                                                              │ DynamoDB em_actions_*
                                                              │ Payability internal API (permissions, users)
                                                              │ Event logger / Messaging / B2B documents
                                                              │
                                              lambda:Invoke (Event)
                                                              ▼
  em_actions_tasks stream ─────────────────────────►  WorkerFunction
  EventBridge rate(4 days) ────────────────────────►    │ Slack DMs, notification emails, event log entries
                                                        │ task counters (em_actions_tasks_counters)
If you want… Read

The big picture: functions, resources, layers

System architecture

How one request flows end to end

Request lifecycle

Every endpoint, its headers and payloads

API overview

What runs in the background and why

Worker Lambda & async tasks · Task counters

Table names, keys and indexes

DynamoDB tables

The services this one calls

Event logger and the other Integrations pages

Running it locally, configuring it, shipping it

Local development · Configuration & secrets · Deployment

Moving production off Zappa

Zappa → SAM cutover

A term you do not recognise

Glossary

Repository layout

Path Contents

lambda_handlers.py

Lambda entry points: api_handler and worker_handler.

run.py

Builds the Flask app (create_app("config")) and initialises Sentry.

config.py

Flask config object; reads every setting from os.environ.

secrets_loader.py

Loads the Secrets Manager secret into os.environ.

actionstools_app/

Application package, one sub-package per resource — see Source map.

tests/

unittest suite, offline (moto for DynamoDB).

template.yaml, samconfig.toml

SAM template and per-environment deploy config.

pyproject.toml, uv.lock, Makefile

uv project and developer commands.

.github/workflows/

GitHub Actions: tests on pull requests, deploys from develop (stage) / release (prod).

scripts/, examples/

One-off maintenance scripts and API usage examples.

docs/

This Antora documentation component.

Tech stack

Python 3.12 · Flask 3 · flask-restx · apig-wsgi · flask-dynamo · boto3 · pyb_flask_utils, eventlogger, messaging (internal SDKs) · slack_sdk · Sentry · AWS (Lambda, API Gateway, DynamoDB, Secrets Manager, EventBridge, CloudFormation/SAM) · GitHub Actions · uv.