From b1c2832245fc08d48d4968ccb288d008f7d8ae67 Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Mon, 6 Apr 2026 10:46:39 +0200
Subject: [PATCH] docs: update architecture with bootstrap phases, scopes,
 branding

- CLAUDE.md: add bootstrap phase listing, document 13 scopes (10
  platform + 3 server), server role mapping via scope claim, admin
  console access, sign-in branding
- Mark server-role-mapping and logto-admin-branding specs as implemented

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     | 21 ++++++++++++++++++-
 ...6-04-06-logto-admin-and-branding-design.md |  2 +-
 .../2026-04-06-server-role-mapping-design.md  |  2 +-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a67d956..0e6fc8b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,7 +46,9 @@ All services on one hostname. Two env vars control everything: `PUBLIC_HOST` + `
 
 - All API endpoints enforce OAuth2 scopes via `@PreAuthorize("hasAuthority('SCOPE_xxx')")` annotations
 - Tenant isolation enforced by `TenantIsolationInterceptor` (a single `HandlerInterceptor` on `/api/**` that resolves JWT org_id to TenantContext and validates `{tenantId}`, `{environmentId}`, `{appId}` path variables; fail-closed, platform admins bypass)
-- 10 OAuth2 scopes defined on the Logto API resource (`https://api.cameleer.local`), served to the frontend from `GET /platform/api/config`
+- 13 OAuth2 scopes on the Logto API resource (`https://api.cameleer.local`): 10 platform scopes + 3 server scopes (`server:admin`, `server:operator`, `server:viewer`), served to the frontend from `GET /platform/api/config`
+- Server scopes map to server RBAC roles via JWT `scope` claim (server reads `rolesClaim: "scope"`)
+- Org role `admin` gets `server:admin`, org role `member` gets `server:viewer`
 - Custom `JwtDecoder` in `SecurityConfig.java` — ES384 algorithm, `at+jwt` token type, split issuer-uri (string validation) / jwk-set-uri (Docker-internal fetch)
 
 ### Server integration (cameleer3-server env vars)
@@ -59,6 +61,23 @@ All services on one hostname. Two env vars control everything: `PUBLIC_HOST` + `
 | `CAMELEER_CORS_ALLOWED_ORIGINS` | `${PUBLIC_PROTOCOL}://${PUBLIC_HOST}` | Allow browser requests through Traefik |
 | `BASE_PATH` (server-ui) | `/server` | React Router basename + `<base>` tag |
 
+### Bootstrap (`docker/logto-bootstrap.sh`)
+
+Idempotent script run via `logto-bootstrap` init container. Phases:
+1. Wait for Logto + server health
+2. Get Management API token (reads `m-default` secret from DB)
+3. Create Logto apps (SPA, Traditional with `skipConsent`, M2M with Management API role)
+3b. Create API resource scopes (10 platform + 3 server scopes)
+4. Create roles (platform-admin, org admin/member with API resource scope assignments)
+5. Create users (SaaS admin with platform-admin role + Logto console access, tenant admin)
+6. Create organization, add users with org roles
+7. Configure cameleer3-server OIDC (`rolesClaim: "scope"`, `audience`, `defaultRoles: ["VIEWER"]`)
+8. Configure Logto sign-in branding (Cameleer colors `#C6820E`/`#D4941E`, logo from `/platform/logo.svg`)
+9. Cleanup seeded Logto apps
+10. Write bootstrap results to `/data/logto-bootstrap.json`
+
+SaaS admin credentials (`SAAS_ADMIN_USER`/`SAAS_ADMIN_PASS`) work for both the SaaS platform and the Logto console (port 3002).
+
 ## Related Conventions
 
 - Gitea-hosted: `gitea.siegeln.net/cameleer/`
diff --git a/docs/superpowers/specs/2026-04-06-logto-admin-and-branding-design.md b/docs/superpowers/specs/2026-04-06-logto-admin-and-branding-design.md
index 3761892..7197a37 100644
--- a/docs/superpowers/specs/2026-04-06-logto-admin-and-branding-design.md
+++ b/docs/superpowers/specs/2026-04-06-logto-admin-and-branding-design.md
@@ -1,4 +1,4 @@
-# Logto Admin Credentials + Sign-In Branding
+# Logto Admin Credentials + Sign-In Branding — IMPLEMENTED
 
 ## Problem
 
diff --git a/docs/superpowers/specs/2026-04-06-server-role-mapping-design.md b/docs/superpowers/specs/2026-04-06-server-role-mapping-design.md
index 9c9565c..8f7d3ff 100644
--- a/docs/superpowers/specs/2026-04-06-server-role-mapping-design.md
+++ b/docs/superpowers/specs/2026-04-06-server-role-mapping-design.md
@@ -1,4 +1,4 @@
-# Server Role Mapping via Logto Scopes
+# Server Role Mapping via Logto Scopes — IMPLEMENTED
 
 ## Problem