---
title: Architecture
slug: tv-toolbox/architecture
icon: {"lucideIcon":"Workflow"}
createdAt: 2026-10-13T09:14:58.288Z
---

TV Lab Tooling is an Adobe App Builder application. It runs inside the Adobe Experience Cloud shell and combines a React Spectrum frontend with Adobe I/O Runtime actions (Node.js) that sit on top of a pluggable database layer.

## Components

The frontend lives in `web-src/src`: `Pages` holds the routed pages, `components` the UI, `functions` the client-side API wrappers, and `config` the sidenav configuration.

The backend lives in `actions`, with these actions:

- `get-sandboxes` lists AEP sandboxes.
- `get-ims-data` fetches and caches IMS users and groups.
- `db-read`, `db-write`, and `db-utils` provide generic reads, generic writes, and administrative database operations.
- `sandbox-cleanup` fetches sandbox objects and executes cleanups.
- `persistence` is the database-agnostic layer all of these use.

## Persistence layer

Actions never talk to a database directly. They use a facade, `actions/persistence`, that selects a driver at runtime from the `DB_PROVIDER` environment variable: `dynamodb` (default) or `mongodb`. Both drivers expose the same API, so action handlers don't depend on the storage. Table and collection definitions come from one registry, `actions/persistence/table-schemas.js`.

## Security

Every action validates its request through `actions/security.js` before doing any work. The request must carry the expected API key, a matching IMS org, and a well-formed Adobe authentication token.

## Permission policy

`permission-policy.json` is an admin-managed file that defines a library of permission resources and which orgs receive them. Only app admins edit it.

`permissionResourceLibrary` holds reusable resource templates, each with a name, label, description, and options. `orgAssignments` maps an org to the resources it should receive, either all options of a template or a list of option names. An optional `ui` block can switch page behavior, such as `allowCreateResource`.

The policy reaches an org's database in two ways: during database initialization (the "Apply permission policy" step), and on demand with **Refresh Policy** on the Permission Resources page. If a resource doesn't exist for the org yet, it is created in full from the template. If it already exists, only new options are appended. Label changes, removed options, and renamed options are not applied to orgs that were already seeded.
