@syntroper/syntroper-in-backstage

View and browse your Syntroper architecture and sequence diagrams directly inside Backstage.

Installation

yarn --cwd packages/app add @syntroper/syntroper-in-backstage
yarn --cwd packages/backend add @syntroper/syntroper-in-backstage

Setup

Backend

Add to packages/backend/src/index.ts:

backend.add(import('@syntroper/syntroper-in-backstage/backend'));

Frontend

Add to packages/app/src/App.tsx:

import { SyntroperPage } from '@syntroper/syntroper-in-backstage';

// Inside <FlatRoutes>
<Route path="/syntroper" element={<SyntroperPage />} />

Sidebar (optional)

Add to packages/app/src/components/Root/Root.tsx:

import { SyntroperIcon } from '@syntroper/syntroper-in-backstage';

<SidebarItem icon={SyntroperIcon} to="syntroper" text="Syntroper" />

Content Security Policy

Add to app-config.yaml to enable diagram previews:

backend:
  csp:
    frame-src: ["'self'", "https://*.syntroper.ai"]

That's it. No environment variables, no API keys, no extra database setup.

Usage

1. Go to /syntroper in your Backstage instance
2. Click Sign in with Syntroper
3. Authorize on Syntroper
4. Browse and preview your diagrams

How It Works

The plugin uses a Backend-For-Frontend (BFF) pattern for security:

• OAuth with PKCE -- no client secret is ever exposed
• Tokens stay server-side -- nothing stored in the browser
• Refresh tokens are encrypted -- AES-256-CBC using your Backstage backend.auth.keys secret
• Diagram previews use one-time tickets -- 60-second TTL, single use
• Works with any database -- PostgreSQL, SQLite, or whatever your Backstage instance uses

User clicks login
  -> Frontend redirects to backend /api/syntroper/auth/start
  -> Backend starts OAuth + PKCE with Syntroper
  -> User authorizes on Syntroper
  -> Backend stores encrypted tokens
  -> User redirected back to Backstage

Requirements

• Backstage instance with backend.auth.keys configured (standard Backstage setup)
• That's it

Register Your Backstage Instance

Before using the plugin, register your Backstage instance on the Syntroper dashboard:

1. Go to https://app.syntroper.ai/dashboard/integrations/backstage
2. Click Add Backstage Instance
3. Fill in the fields:

| Field | Description | Example | |---|---|---| | Instance Name | A unique identifier for your instance | my-company-prod | | Description | A note to identify this instance | Production Environment deployed on-prem | | Redirect URL | Your Backstage backend callback URL | https://backstage.yourcompany.com/api/syntroper/auth/callback |

4. Click Save

For local development, use http://localhost:7007/api/syntroper/auth/callback as the Redirect URL.

Troubleshooting

"Encryption secret is required" Your Backstage instance needs backend.auth.keys in app-config.yaml:

backend:
  auth:
    keys:
      - secret: your-secret-min-32-chars

Diagrams not rendering Add the CSP rule from the setup section above.

OAuth redirect fails Make sure the callback URL in Syntroper matches {backend.baseUrl}/api/syntroper/auth/callback.

Support

• Email: [email protected]