刀豆 Console Engineering Design Document · Part 02. Status: rewritten to match the implemented code (2026-07-16). This article addresses only how the system is layered, which side owns each type of data, and how the two sides communicate. For authentication, see 03; for integration configuration, see 05; for the database, see 13; and for the project contract, see 18.
刀豆 Console is the unified control plane, while each project is an autonomous runtime plane. Console centrally manages identities, permissions, content, versions, and publishing; each project retains its own admin business logic, component implementations, and frontend rendering. The two sides communicate only through versioned REST, JWT/JWKS, HMAC, and browser postMessage. They share neither processes nor business databases, and neither duplicates the other's rendering code.
Four non-negotiable principles:
Layered authority: The source definitions for component fields/sample reside in project code, while Console DB stores the per-env LKG that has passed contract validation. For Landing/Blog, Console DB is the sole source of truth for identities, drafts, and the currently published snapshots.
Rendering belongs to the project: Component structure and data reside in Console, while component styles and the renderer reside in the project. Both preview and production use the project's own renderer.
Separate security surfaces: A project's Admin and Content/Preview integrations can be connected independently, with different configurations, credentials, sessions, cookies, and permission targets.
Physical environment separation: The control plane is in platform, test content is in test, and production content is in prod. The test/prod configurations are also two independent records, with no implicit inheritance.
Console is responsible for:
Better Auth platform identities, users, projects, roles, and three-dimensional RBAC.
Configuration, credentials, enablement, disablement, and auditing for the two project integration types: Admin and Content.
Logical landing pages, complete localized pages, shared component topology, Blog, multilingual content, SEO, theme selection, and exact component references.
Drafts are saved explicitly (D-95: users decide when to save, with a warning when leaving with unsaved changes); Landing A/B/C checks and environment application; Blog Test/Prod mirrors Draft/Published and publishes directly and atomically.
Project capability synchronization and last-known-good projections.
Real-time transfer of editing state to iframe previews, plus authorization for reading drafts in separate preview windows.
Console is not responsible for:
The business logic and business data of the project's admin system.
The React/Vue/CSS implementation of project components.
The project's choice of frontend routing framework or SSR/SSG/ISR strategy.
The password for the project's business database.
Running Redis or using it to store any platform state. Rate limits, project SID/leases, and replay prevention have all been consolidated into PostgreSQL.
The project is responsible for:
Its own admin business logic, business database, and server-side authorization guards.
The component registry, the schema/renderer and actual styles for each exact technicalName; the project generates the componentId.
Capability endpoints for languages, themes, color modes, the component manifest, Preview, and revalidation.
Admin/Preview Bridge JWT validation and their respective local sessions.
The frontend reads published content from Console's published API, then caches and renders it using SSR/SSG/ISR according to the project's strategy.
Auditing key business actions on the project side and reconciling them with Console records using requestId.
The project must not save edited content separately as a second authoritative CMS; any local cache may only be a disposable cache of published content.
┌────────────────────────── Console 控制面 :8888 ──────────────────────────┐
│ Better Auth │ 项目/RBAC │ Admin Integration │ Content Integration │
│ │ │ │ │
│ platform schema: 用户/Session、项目、接入、安全短状态、能力投影、审计 │
│ test schema: Landing Draft/Test；Blog Draft/Published；环境 taxonomy │
│ prod schema: Landing Prod C；Blog Draft A/Published B 当前槽位 │
└───────────────┬──────────────────────────────┬───────────────────────────┘
│ │
Admin 身份与复核 Content/Preview 契约
JWT/JWKS + HMAC HMAC + Preview JWT + REST
│ │
┌───────────────▼──────────────────────────────▼───────────────────────────┐
│ Project Launchpad / 其他项目运行面 │
│ /admin 业务后台 │ 项目业务库 │ component registry │ Preview renderer │
│ 项目本地 Session│ │ 前台 SSR/SSG/ISR │ revalidate/capability│
└───────────────────────────────────────────────────────────────────────────┘
A project can use Content Integration without Admin Integration, or it can use only Admin. Deploying them on the same domain does not change the principle of separating security surfaces.
Console iframe entry point:
Console 校验平台 Session 与项目准入
→ 签发约 120 秒 Admin Bridge JWT
→ iframe 打开项目 embedded bridge
→ 项目用 Console JWKS 验签，并核对 project/env/target
→ 项目写入本地 Admin Session Cookie
→ 回到原 /admin deep link
Open the project admin directly:
项目 /admin 无本地 Session
→ 项目生成独立 state transaction
→ 跳 Console authorize
→ Console 有 Session：直接验权；无 Session：先登录
→ Console 签 standalone Bridge JWT
→ 项目核对 state + JWT，建立本地 Session
→ 回原 deep link
Bridge JWT handles only a one-time identity handoff; it is not a long-lived access token. A project Session lasts up to 7 days, and the project's server-side guard revalidates permissions with Console every 5 minutes. Logging out locally from the project clears only the project Session, not the Console Session.
Console Landing Draft A
→ 强制检查后覆盖 Test B
→ 强制生产检查后覆盖 Prod C
→ 记录发布人/revision/审计
→ HMAC 通知项目 revalidate
→ 项目前台重新读取 published API / 更新本地缓存
Content moves; configuration and credentials do not. A production project reads the published-state Console API but cannot access the draft endpoint. If the cache is invalidated, it can fall back to the origin; Console does not push an editable database copy to the project.
Console 编辑器内存态
├─ iframe：postMessage 实时覆盖项目 Preview renderer
└─ DB：有变化时 debounce 1 秒，持续输入 maxWait 30 秒
独立 Preview 窗口
→ Preview Session 鉴权
→ 读取 Console 草稿接口
→ 每 5 秒按 revision 轮询；无变化不重复渲染
Preview and Admin share the platform identity root and JWT/JWKS/HMAC infrastructure, but they do not share Cookie, Session, target, or long-lived credentials. The iframe's postMessage carries only protocol-defined editing data, not the HMAC secret.
Data | Single Source of Truth | Project-Side Form |
|---|---|---|
Platform Users and Session |
| Receives only a short-lived Bridge identity and does not replicate the platform Session |
Rate limiting, project SID/leases, and replay prevention |
| The project calls consume/revalidate/logout only as defined by the contract and does not hold Console storage |
User's Recent Activity |
| No three-state online status; not synced to the project |
Project Members and Permissions |
| The local Session stores the necessary snapshot; permissions are revalidated every 5 minutes |
Admin Integration |
| Admin Credential and protocol endpoints in environment variables |
Content/Preview Integration |
| Content Credential and protocol endpoints in environment variables |
Component manifest/schema/sample | Console Synchronized Projection | The project registry is the source of declarations, while Console DB is the synchronized source of truth used for content orchestration |
Pages/Blog/Drafts |
| Does not store an editable authoritative copy |
Published-state cache | Console publishing API | The project may be cached or rendered statically, but it must be rebuildable |
Component styles and renderer | Project repository | Preview and production reuse the same project implementation |
Content tables use project_id for project isolation; the legacy tenant_id terminology is not used. The user/project identifiers in audit tables are snapshots taken at write time and have no FK, ensuring that the history remains readable after the associated entity is deleted.
The environment has two dimensions that must not be conflated:
Content environment: test / prod schema. Edits go only to test; only promote can write to prod.
Project deployment environment: Each Integration has separate test and prod configurations, with fully independent Origin, path, credentials, and status values.
The UI may provide a “Copy Test fields to the Prod form” option, but once saved, it becomes an independent Prod record; subsequent changes to Test do not affect Prod. Production Origin requires HTTPS, while local test permits HTTP.
The project declares the following through Content capabilities:
Supported locales and the default locale.
Supported themes, the default theme, and the color modes allowed for each theme.
The component manifest endpoint and stable Preview path.
Protocol endpoints such as revalidate.
Console proactively fetches capabilities using Content HMAC and stores the last-known-good version. A component's identity is the project-generated componentId + technicalName: the same technical name identifies the same version, and content references that name exactly. Only current live production references lock fields; a breaking new version uses a new ID and technical name. If it is missing, fail closed rather than guessing another version.
Capability synchronization is not a content fallback: when a project endpoint is unavailable, the most recent successful snapshot may be displayed, but mock capabilities must not be fabricated, and a failed synchronization must not be treated as successful.
Every request must satisfy all of the following:
有效平台身份
∩ 有效项目成员关系
∩ permission domain
∩ environment scope
∩ 资源自身状态约束
Typical role tiers:
Operations member: Can access the admin area of authorized projects and edit content, but cannot view integration credentials.
Developer: Can view the Admin/Content integration configuration but cannot modify it.
Project owner: Can save credentials, enable or disable them, and reissue them. For immediately effective actions such as enabling, disabling, or reissuing credentials, the frontend displays a confirmation dialog, while the server relies solely on three-dimensional RBAC for access control (D-85).
The Admin Credential signs only Admin verification requests; the Content Credential signs only capability, content, and revalidate requests. Cross-surface verification and fallback are strictly prohibited.
2PC is not used across systems; instead, the design uses idempotency, requestId, audits on both sides, and retryable compensation.
A Preview disconnection does not affect draft saving; if saving a draft fails, the system does not pretend it was saved.
A revalidate failure does not roll back a successful promote operation, but it must be observable and retryable.
When a project endpoint is unreachable, Admin/Preview fails explicitly instead of falling back to the Console mock page.
Configurations in the active state are frozen; they must be disabled before modification or single-credential re-signing.
When PostgreSQL is unavailable, Bridge fails closed for one-time consumption; standard HMAC replay protection and auxiliary rate limiting each retain their established failure policies rather than being merged into a single policy simply because both use PG.
Expired SID, replay, and rate-limit rows are cleaned up every 15 minutes; cleanup failures affect capacity only and do not change request-time expiration checks.
Current production-readiness gaps: a pre-enable readiness probe, a reliable outbox for critical audits, concurrent CAS, and zero-downtime credential rotation with multiple kid values. See 15 §9 for details.
“Moving all project components into a shared renderer in Console” would create three new problems:
Console would have to release alongside every project's UI framework and dependencies, recreating coupling with the main repository.
The preview could differ from the actual code used in the project's production deployment, undermining consistency instead.
Project-specific styles, runtime capabilities, and data sources would be forced to leak into the platform.
Therefore, only protocols and pure type contracts are shared, not a specific UI renderer. “Preview-production consistency” means that a project's Preview and Production environments reuse the same renderer from the project repository, not that Console copies the renderer.
/Users/edwin/coding/diaoyan/project-launchpad is the first real reference project:
Both the Admin iframe and standalone SSO flows have been validated.
After a local project logout, the Console session can be silently reused.
Content HMAC capability synchronization and the component manifest have been persisted to the database.
15 component families and 16 immutable versions can be previewed individually in Console.
Themes and light/dark/system modes are declared through project capabilities; the component canvas background is independent of the component mode.
Future projects must replicate the contracts and boundaries, not Project Launchpad's business UI or technology stack.
