High-Level System Architecture — “who talks to whom”

1. Access app (User → wizbrand-web)
The user opens your Laravel frontend (wizbrand-web). If there’s no signed-in session, the app will trigger OIDC login (next step).

2. OIDC Auth (wizbrand-web → Keycloak)
wizbrand-web redirects the browser to Keycloak (realm: wizbrand) using Authorization Code + PKCE.
Purpose: prove user identity and get tokens (ID, Access, Refresh).

3. Tokens back (Keycloak → wizbrand-web)
Keycloak calls back to your redirect URI with a code. Your backend exchanges it for tokens that include custom claims:

• org_memberships: per-org roles like ORG_ADMIN|ORG_MANAGER|ORG_USER
• tenant_ids: convenience list of the user’s org IDs
• (preferred_org: added later after org selection)

4. API calls (wizbrand-web → wizbrand-api)
Your frontend (or server side) calls your API with the Access Token (audience includes wizbrand-api).
The API verifies the JWT (JWK), checks aud, exp, and authorization (role + current org).

5. Access sidecar app (User → oauth2-proxy)
For SEO panel, Navidrome, FileBrowser, Piwigo, the user hits a gateway/proxy first (e.g., oauth2-proxy, Traefik ForwardAuth, or Envoy). This proxy is an OIDC client of Keycloak.

6. OIDC (silent/login) (oauth2-proxy ↔ Keycloak)
If the browser still has a Keycloak SSO session, the proxy does silent auth; otherwise it shows the Keycloak login screen. No separate app accounts are needed.

7. Tokens to proxy (Keycloak → oauth2-proxy)
Keycloak issues tokens (with the same claims). The proxy validates them and enforces tenant & role.

8. Forward identity & org headers (oauth2-proxy → Sidecar app)
If authorized, the proxy forwards identity as headers to the sidecar app, for example:

• X-User-Id: <sub>
• X-User-Email: <email>
• X-Org-Slug: <preferred_org> (or org from path/host)
• X-Org-Roles: ORG_ADMIN,ORG_MANAGER
  The sidecar apps can stay mostly unmodified; the proxy does the authZ gate.

(Dashed) Optional: entitlements API (wizbrand-api → proxy)
If you want extra checks (quotas/features per org), the proxy can call your API to fetch entitlements before allowing access.

Provisioning/Sync Worker → Keycloak
Your backend “worker” (or admin microservice) uses the Keycloak Admin API to:

• create Groups /orgs/{org_slug} with attributes (org_id, plan, features[])
• add/remove users to those groups
• map per-org roles (ORG_ADMIN|ORG_MANAGER|ORG_USER)