Pitch: Tolgee Apps — from POC to production

[JanCizmar]

Pitch: Tolgee Apps — from POC to production

1. Problem

Tolgee cannot be extended without forking or upstreaming. Every customer-specific need — a semantic back-translation check, glossary enforcement, linking keys to an external system — either becomes a feature request competing for core capacity, or doesn't happen at all. Competitors (Crowdin Apps, Atlassian Connect ecosystem) let third parties build on the platform; we have no story.

The hackathon produced a working plugin system POC (jancizmar/tolgee-apps-poc, architecture in docs/dev-notes/TOLGEE_APPS_ARCHITECTURE.md): manifest-registered apps render sandboxed iframes across the product, call the REST API with signed short-lived JWTs, and react to webhooks. Three example apps (dev-plugin, back-translate, glossary-keeper) were built against it with an SDK, CLI, and generator. The baseline problem now: this all lives on one giant unreviewed branch (~275 files). Nobody but the author can vouch for it, the security surface (iframes, tokens, SSRF, scope escalation) has never had focused review, and it can't merge as-is.

2. Appetite

4 weeks — two cycles worth of calendar time, one developer.

• Weeks 1–2 — implementation: extract the POC into ~9 vertically-integrated, UI-testable scopes (each ≈ one PR), merged to main behind a tolgee.apps.enabled flag, each with e2e proof that an SDK-built app works against it.
• Weeks 3–4 — team review: reviewers work through the per-scope PRs; the developer addresses findings, hardens security per review feedback, and finishes docs.

3. Solution

The engine gives an app author three capabilities, delivered in this order, each proven end-to-end in the UI before the next starts:

Foundation — register & enable. Org settings → Apps: admin pastes a manifest URL, Tolgee fetches + validates it (SSRF-guarded, HTTPS-only), shows the parsed modules, stores the install. Project settings → Apps: project admin toggles the app per project. Disabled = invisible everywhere.

Pillar 1 — apps use the REST API. An enabled app's project-dashboard-page module appears in the project sidebar; clicking mounts a sandboxed iframe. postMessage handshake delivers a Tolgee-signed JWT (install/org/project/user claims, short TTL); the app calls /v2/... with it. Enforcement is scope-cap ∩ user-role. Proven by an SDK example app that reads and writes a translation from its page, asserted by Cypress.

Pillar 2 — apps enhance the UI. Same iframe host reused across: translation tools panel (receives live selection), key-edit dialog tab, key/translation action decorators (static + dynamic via the app's decoratorsUrl, count badges), and — nice-to-have — modals with five trigger surfaces including keyboard shortcuts.

Pillar 3 — apps react to webhooks. Manifest webhooks.events (validated against ActivityType) auto-provisions app-managed webhook configs. Demoed as the back-translate loop: edit a translation → webhook fires → app's decorator badge updates.

Growing alongside every scope: @tolgee/apps-sdk (context, selection, API helpers), the e2e suite (a real SDK app per scope), and the docs section in the documentation repo. UI is not redesigned — the POC's UI, already user-validated in the hackathon, serves as the mockup (deliberate deviation from our "Figma during shaping" rule).

5. No-gos

• No ZIP-based plugin delivery, no marketplace/directory, no app discovery UI.

6. Success criteria

• The time to deliver a prototype of customer specific feature is shorter
• User's understand apps and create their own
• We have 20 registered user apps in 2 months

[JanCizmar]

Building Plan / Scope Map

Appetite: 4 weeks (2 weeks implementation + 2 weeks team review of per-scope PRs)
Source: extraction from battle-tested POC branch jancizmar/tolgee-apps-poc — each scope ≈ one PR merged to main behind tolgee.apps.enabled (default off).

Every scope is a vertically-integrated, UI-testable slice (BE + FE) and ends with a Cypress e2e test where a real SDK-built app proves the slice works. The SDK/CLI and e2e tooling grow inside each scope, not as a separate track.

First slice

Scope 2 (App shows its page), thinned: register a manifest → enable in a project → sandboxed iframe renders with a completed handshake, one Cypress test with a mock SDK app. Core, small, novel (sandboxing + origin rules live here). Target: demoable by day 3.

Scope map

1. Register & enable an app

• BE: AppInstall / AppEnabledForProject entities, changelog, org + project apps controllers (register / preview / refresh / remove / enable)
• BE: manifest fetch + validation (AppManifestFetcher)
• FE: org settings "Registered apps" screen with Register/Refresh dialogs; project settings enable toggle
• Security step 1: SSRF guard on manifest fetch, HTTPS-only in prod (allow-local-addresses for dev), admin-only endpoints
• Feature flag tolgee.apps.enabled (default off)
• Tooling/e2e: mock manifest fixture server; Cypress: register → see parsed manifest → enable in project
• ~ Browser-based install flow (InstallAppView)
• I think I know how to do it
• I have validated my approach

2. App shows its page

• BE: /v2/projects/{id}/apps listing endpoint consumed by the webapp
• FE: sidebar entry from manifest, route, sandboxed iframe, ready/init/resize postMessage core
• Security step 2: <iframe sandbox> + postMessage origin rules (decided in pitch)
• Tooling/e2e: SDK getContext() handshake; Cypress: example app renders and echoes its context
• I think I know how to do it
• I have validated my approach

3. App acts through the REST API (pillar 1 complete)

• BE: token mint endpoint, JWT signing + TTL, AuthenticationFilter app-token path, scope enforcement, AppSelfController
• FE: token delivery to iframe via postMessage; SDK API helper (ctx.token → authorized fetch)
• Security step 3: scope caps, no silent scope escalation, acting-as bounds, filter + interception tests (port from POC)
• Tooling/e2e: example app reads and writes a translation via SDK; Cypress asserts the edit landed
• ~ JWKS endpoint for app backends to verify tokens offline
• I think I know how to do it
• I have validated my approach

Iceberg scope (heavy BE, thin FE) — the deliberate exception to the vertical rule; the UI-testable proof is the example app visibly mutating a translation.

4. App joins the translations view

• FE: tools-panel module, selection context in init, selection-changed, resize, panel header icon/title
• Tooling/e2e: SDK selection subscription; Cypress: select a key → panel app shows its name
• ~ translation-tools-panel-empty extension point + selected languages
• I think I know how to do it
• I have validated my approach

5. App inside the key edit dialog

• FE: key-edit-tab module, tab-only dialog mode when user lacks keys.edit
• Tooling/e2e: Cypress: open key → app tab renders with key context
• I think I know how to do it
• I have validated my approach

6. Apps decorate keys & translations

• FE: static + dynamic decorators, decoratorsUrl protocol, count badges, visibility rules, panel/tab reveal actions
• Security step 4: webapp→app-backend direct calls — CORS contract, what the token exposes to the app's server
• Tooling/e2e: example app serves a decorators endpoint; Cypress: badge appears, click opens the panel
• I think I know how to do it
• I have validated my approach

7. Apps react to events (pillar 3)

• BE: manifest webhooks.events → app-managed webhook configs (AppManagedAutomationService), event-name validation against ActivityType
• Security step 5: webhook payload signing / app-backend verification story
• Tooling/e2e: edit a translation → webhook fires → app's decorator updates (back-translate pattern); fallback assertion at mock app server if flaky
• I think I know how to do it
• I have validated my approach

~ 8. Apps open modals from anywhere

• Modal module + 5 trigger surfaces (bulk, toolbar, sidebar, key-edit footer, shortcuts)
• Cypress: shortcut opens modal with selectedKeyIds
• I think I know how to do it
• I have validated my approach

~ 9. Org-level apps (glossary)

• Org-scope authorization (AllowAppAccessWithOrgScope), ee glossary access, glossary-keeper example
• Security step 6: org-scope bounds tests
• I think I know how to do it
• I have validated my approach

Docs

• Port the tolgee-apps/ documentation-repo section, updated per scope as protocols firm up
• Promote TOLGEE_APPS_ARCHITECTURE.md from dev-notes to a maintained reference
• I think I know how to do it
• I have validated my approach

Chowder

• Move SDK/CLI/example apps to a separate repo (decided in pitch — keeps 31k-line lockfile out of platform PRs)
• Theme passing to iframes (fold into scope 2 or 4)
• ~ create-tolgee-app generator + dev CLI tunnel polish (works at alpha; can trail the cycle)

Sequence (implementation weeks)

1. Days 1–3: Scope 1 (thin) + Scope 2 first slice — get sandboxing/origin decisions over the hill immediately.
2. Days 4–5: Scope 3 — the security core, reviewed alone with nothing else in the diff. End of week 1: pillar 1 shipped and e2e-proven.
3. Days 6–8: Scopes 4, 5, 6 — UI pillar, mostly downhill ports from the POC.
4. Days 9–10: Scope 7 + docs + scope hammering. Scopes 8–9 only if time allows.

Review weeks (3–4): reviewers work through PRs in scope order; author addresses findings and finishes docs.

Must-haves vs nice-to-haves

Must: scopes 1–7, docs, feature flag — the full three-pillar story.
Nice-to-have (~): modals/shortcuts, org-level glossary, install-view flow, JWKS, generator polish. Cutting all of them still ships a complete apps platform vs. today's baseline (nothing).

Risks and mitigations

• Sandboxing/token-transport decisions reopen: front-loaded to days 1–5 so a surprise re-enters shaping instead of blowing the cycle.
• Review latency: feature flag means each PR merges independently — no stacked rebasing.
• Webhook e2e flakiness: fallback assertion at the mock app server.