Data and storage model

Mode: reference.

All Tollgate data is held inside Atlassian Forge storage. There are no external databases, no external servers and no data egress — the app is Forge-hosted end to end (a “Runs on Atlassian” constraint). Tenant isolation is provided by Forge: every storage read/write is scoped to the installing site, and keys additionally include a project identifier so no project can read another’s governance data.

Two storage modes (ADR-0004)

Tollgate uses both Forge storage APIs.

Mode	Holds	Shape
Custom Entity Store (CES)	The high-volume per-project collections: work packages, RAID/risk items, decisions, changes, and the audit log.	One record per entity, up to 240 KiB per record. Each has a by-project index.
Key-Value Store (KVS)	Singleton and config data: charter / business case, project status, phase bands, per-project settings, and site-level config.	Keyed values (e.g. status:{projectKey}, config:{projectKey}).

CES entities

Declared in manifest.yml under app.storage.entities. Each record carries a projectKey (partition) and either an id or ts (range), plus the entity’s payload serialised into a self-describing data attribute.

Entity	Partition	Range	Notes
work-package	projectKey	id	Work package records.
raid-item	projectKey	id	R/I/O (risk / opportunity / materialised) register.
decision	projectKey	id	Decision log.
change	projectKey	id	Change requests.
audit-entry	projectKey	ts	Governance audit trail; ranges on ts for newest-first reads.

Caution

CES entities and attributes cannot be removed once deployed and cannot be backported. Treat schema additions as permanent and additive-only (ADR-0004). Because payloads are stored as a serialised data blob, the record schema evolves in code, not in the manifest.

Data lifecycle and GDPR

Tollgate registers Forge lifecycle handlers so governance data does not outlive the Jira objects it describes.

Trigger / module	Forge event	Handler	Effect
project-deleted-trigger	avi:jira:deleted:project	handle-project-deletion	Purges all app data for the deleted project.
user-deleted-trigger	avi:jira:deleted:user	handle-user-deletion	GDPR right-to-be-forgotten: scrubs the user’s accountId from per-project records.
preUninstall module	app uninstall	handle-app-uninstall	Synchronous tenant-wide data purge, within Forge’s ~55-second pre-uninstall window.

Personal-data minimisation

• Tollgate stores Jira accountId references, not names. Display names are resolved from Jira only when rendered in the UI.
• Logs must not contain personal data or sensitive governance content.
• Forge provides encryption at rest.

Note

preUninstall is a distinct Forge module type (not a trigger event) precisely because it runs synchronously before the uninstall proceeds, giving the app a bounded window to purge tenant data.

TODO: confirm with James

The KVS key patterns (status:{projectKey}, config:{projectKey}) are drawn from the architecture overview and the (historical) MVP1 spec; some conceptual per-key patterns in that spec were superseded by CES. Confirm the exact current KVS key set against src/constants.js before relying on specific key names.