Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,43 @@
# Admin-Managed Feature Pattern
Use this when a tenant uses a feature whose policy, provider, key or global availability is controlled by the admin/platform.
## Definition
An admin-managed feature is configured by admin/platform operators and consumed by tenants. Tenants may see enabled state and allowed options, but they do not own sensitive provider configuration.
## Examples
- Tenant AI chatbot using an admin-owned AI provider key approved for the deployment region.
- Tenant integration using a platform-owned provider account.
- Tenant feature enabled only for selected plans or accounts.
- Browser automation where admin controls allowed domains and runtime policy.
## Required Manifest Entries
The feature manifest must declare:
- `integration.ownership = "admin-managed"` or `"hybrid"`.
- Admin routes that manage provider/policy.
- Tenant routes that consume the feature.
- Secrets and who owns them.
- Permissions for admin configuration and tenant usage.
- Audit events for configuration changes.
- Billing and usage impact.
- UAT checks for secret isolation and tenant enablement.
## Security Rules
- Provider keys are never tenant-owned unless explicitly designed as tenant-owned.
- Provider keys must not be sent to tenant loaders, API responses, browser bundles or logs.
- Admin policy must be checked server-side.
- Tenant enablement must be checked server-side.
- Admin configuration changes must emit audit events.
## Implementation Shape
- Admin settings store provider config, model/default policy, enablement and limits.
- Tenant feature state references admin-approved config.
- Tenant UI shows only allowed choices.
- API routes resolve effective configuration server-side.
- Worker jobs receive scoped IDs and load secrets server-side.
@@ -0,0 +1,68 @@
# Feature Integration Playbook
Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product.
## Goal
Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it.
## Required Steps
1. Read `docs/agent-entrypoints.md`.
2. Find or create a manifest in `docs/feature-manifests/`.
3. Classify ownership:
- `tenant-owned`: tenant configures and uses it.
- `admin-managed`: admin/platform configures it; tenant only uses approved surfaces.
- `hybrid`: admin defines policy/defaults; tenant can configure local behavior.
- `system-only`: internal platform feature with no tenant-owned controls.
4. Map surfaces:
- Admin route source files and canonical admin-host runtime paths.
- Tenant route source files and canonical tenant-host runtime paths.
- Public route source files and root/web-host runtime paths.
- API route source files and canonical API-host `/v1/...` runtime paths.
- Link/form/action helpers: `adminPath`, `appPath`, `apiPath`, cross-host helpers, or `UrlUtils.getModulePath(...)` for tenant modules.
5. Map persistence:
- Prisma models.
- Existing tables reused.
- Migrations required.
- Tenant scoping fields.
6. Map configuration:
- Admin settings.
- Tenant settings.
- Environment variables.
- Secrets and their owner.
7. Map runtime:
- Request/response only.
- Queue-backed.
- Worker-backed.
- Browser-backed.
8. Map controls:
- Permissions.
- Audit events.
- Billing or usage limits.
9. Define UAT:
- Operator-visible checks.
- Negative checks for forbidden access.
- Secret exposure checks if providers are involved.
## Implementation Rules
- Do not expose provider secrets through tenant loaders, API responses, client bundles or logs.
- Do not add sidebar/nav entries without stable UI IDs.
- Do not add new root UI primitives without updating `docs/ui-inventory/components.json`.
- Do not add worker behavior without declaring queues and jobs in the manifest.
- Do not add admin-managed tenant behavior without admin permissions and audit events.
- Keep proprietary feature logic behind explicit module boundaries.
- Do not hard-code legacy runtime paths such as `/admin/...`, `/app/...`, or `/api/v1/...` outside tests that explicitly cover legacy redirects.
- Do not ship visible UI text without locale keys and `pnpm run verify:i18n`.
## Done Criteria
- Manifest updated and valid.
- Routes and surfaces match the manifest.
- Permissions are enforced on admin/API/tenant surfaces.
- Tenant-scope negative tests cover forbidden reads and mutations.
- Route helpers and runtime host ownership are tested for new navigation.
- i18n and deploy/static verifiers relevant to the change have run.
- Required worker queues/jobs exist or are explicitly deferred.
- UAT checks pass or are marked as deferred with a reason.
@@ -0,0 +1,24 @@
# Foundation Boundary Playbook
Use this when moving feature logic into the reusable boilerplate layer or when touching audit, idempotency, flags, permissions, billing usage, or notifications.
## Ownership Rules
- Runtime apps may orchestrate requests, headers, sessions, and responses.
- Shared business rules belong in `packages/*`, preferably `@toolctrl/foundation` for pure policy and `@toolctrl/db` for schema-backed server boundaries.
- UI and route modules must not reach around package boundaries for tenant-scoped persistence.
- Foundation exports must stay generic. Do not add product-specific roles, flags, templates, adapters, or catalog entries.
## Required Checks
- Audit writes use `@toolctrl/db/audit-events.server`.
- Idempotency keys use `@toolctrl/db/idempotency-keys.server` or the API idempotency store bridge.
- API usage limits use `@toolctrl/db/usage.server`; API routes should not recompute subscription feature math locally.
- Notification deliveries use `sourceKey` whenever a producer can derive a stable event key, so DB upsert prevents duplicate delivery records.
- Feature flags resolve in this order: explicit override, user scope, tenant scope, global scope, default.
## Done Criteria
- Add or update focused tests in the owning package.
- Update feature manifests when a feature changes ownership, billing, provider, worker, or admin-managed behavior.
- Run `pnpm run test:foundation`, the affected package tests, and the app-level route tests for changed runtimes.
@@ -0,0 +1,62 @@
# MVP Intake Playbook
Use this before adapting an existing MVP onto this boilerplate.
## Purpose
Prevent agents from copying product code blindly. The MVP must first be decomposed into flows, roles, data, providers, ownership and runtime behavior.
## Intake Checklist
Capture the following before implementation:
- Product summary: what the MVP does in one paragraph.
- Primary user roles.
- Admin/operator roles.
- Tenant roles.
- Critical user flows.
- Data objects and ownership.
- External providers.
- Secrets and credentials.
- Background jobs.
- Browser automation or long-running work.
- Billing or usage limits.
- Existing UI surfaces.
- Must-keep behavior.
- Behavior that should become plugin-only.
- Behavior that should be removed.
## Flow Mapping
For every flow, record:
- Entry point.
- Actor.
- Preconditions.
- Data read.
- Data written.
- Provider calls.
- Sync versus async behavior.
- Success state.
- Failure state.
- UAT check.
## Boilerplate Mapping
Map each flow into:
- `apps/web/app/routes/admin*` for admin/platform management files; runtime links must use `adminPath` or admin-host helpers.
- `apps/web/app/routes/app.$tenant*` for tenant-facing usage files; runtime links must use `appPath`, `UrlUtils.getModulePath(...)`, or an equivalent host-aware wrapper.
- `apps/api/src/app.ts` under `/v1` for canonical public/service APIs and webhooks. If a `/v1` route temporarily proxies a web `internal/api` handler, record `apps/api` as the external route owner and the web handler as the temporary implementation owner until extraction lands.
- `apps/web/app/modules/<feature>` for feature-owned application logic.
- `apps/worker` and `packages/queue` for async jobs.
- `docs/feature-manifests/<feature>.json` for the integration contract.
## Output Required From Agent
Before coding, the agent should produce:
- A short MVP decomposition.
- A feature manifest draft or update.
- A list of unknowns that block safe implementation.
- An implementation plan tied to the manifest.
@@ -0,0 +1,74 @@
# UI Adapter Migration Playbook
Use this when moving UI primitives toward `packages/ui` hotswap-ready adapters.
## Goal
App code should eventually depend on stable adapter contracts such as `@toolctrl/ui/buttons`, not directly on a specific library implementation. Migration happens category by category.
## Migration Order
1. Navigation and shell
2. Buttons
3. Dialogs and modals
4. Tabs and tables
5. Inputs
6. Feedback
## Adapter Levels
- `placeholder`: category exists but exports no real adapter contract.
- `available`: package exposes stable metadata/contract for the current implementation.
- `component-backed`: package exports real reusable components or wrappers.
- `migrated`: app imports use the package adapter instead of app-local primitives.
Current status:
- `buttons`: `available` contract for `Button` and `buttonVariants`.
- `layout`: `available` contract for `ShadcnSidebarLayout` and `UiRegistry`.
- `navigation`: `available` contract for `AppSidebar`, `AdminSidebar`, `DocsSidebar`, `NavMain`, `NavSecondary`, `NavQuickLinks`, `NavActions`, and `SidebarPrimitives`.
- all other categories: placeholder registry.
## Rules
- Start with metadata/contract exports before moving components.
- Keep adapter exports source-only and runtime-safe.
- Keep runtime components in `apps/web/app/` until a migration phase explicitly moves imports.
- Do not import app routes, data loaders, tenant context, admin context, or feature modules into `packages/ui`.
- Do not hide feature-specific behavior inside `packages/ui`.
- Keep shadcn/Radix as the current core default until a category-specific migration says otherwise.
- Treat Headless UI as legacy unless explicitly retained by a category decision.
## Required Checks
For each category migration:
- Update `packages/ui/README.md`.
- Update the relevant `packages/ui/src/<category>.ts`.
- Update `docs/ui-inventory/components.json`.
- Add or update adapter contract tests.
- Keep app imports unchanged unless the phase explicitly migrates them.
## Button Example
Current button adapter contract:
- `@toolctrl/ui/buttons`
- `buttonAdapterNames`
- `buttonAdapters`
- source: `apps/web/app/components/ui/button.tsx`
This records stable intent without moving the current shadcn implementation yet.
## Shell/Navigation Example
Current shell/navigation adapter contracts:
- `@toolctrl/ui/layout`
- `layoutAdapterNames`
- `layoutAdapters`
- `@toolctrl/ui/navigation`
- `navigationAdapterNames`
- `navigationAdapters`
These records point agents to the current runtime sources in `apps/web/app/` and are guarded by `apps/web/app/application/ui/uiAdapters.test.ts` plus the inventory tests.
@@ -0,0 +1,45 @@
# UI Change Playbook
Use this when an agent changes layout, navigation, shell, buttons, dialogs, inputs, tables, feedback UI, or any `apps/web/app/components/ui` primitive.
## First Reads
1. `docs/ui-inventory/surface-map.md`
2. `docs/ui-inventory/surfaces.json`
3. `docs/ui-inventory/components.json`
4. `apps/web/app/application/ui/uiRegistry.ts`
5. `docs/agent-playbooks/ui-adapter-migration.md` if the change touches `packages/ui`
## Agent Workflow
1. Identify the target by `data-ui-id`, not by visual guesswork.
2. Find the source file in `docs/ui-inventory/surfaces.json` or `components.json`.
3. Check whether the change is a surface change, component primitive change, or feature-specific UI change.
4. Preserve or add stable `data-ui-id` attributes for user-visible surfaces and actions.
5. Update `docs/ui-inventory/components.json` when adding root UI primitives.
6. Update `docs/ui-inventory/surfaces.json` when adding or renaming surfaces/actions/navigation IDs.
7. Add or update DOM tests for important `data-ui-id` behavior.
## Rules
- Do not add sidebar/nav items without stable IDs.
- Do not add dynamic UI items without `uiIdPattern` and `uiIdParams`.
- Do not move app components into `packages/ui` unless the adapter migration playbook says the category is ready.
- Do not change `packages/ui` exports in a way that imports app runtime or React components unless that migration phase explicitly owns it.
- Do not rely on visible text alone to locate UI in agent instructions; prefer `data-ui-id`.
## Common Requests
- "Change the app sidebar": start with `ui.surface.app.sidebar`.
- "Change admin sidebar settings": start with `ui.nav.admin.settings`.
- "Change header search": start with `ui.action.shell.search`.
- "Change header right actions": start with `ui.surface.shell.navActions`.
- "Change page content shell": start with `ui.surface.shell.main`.
## Done Criteria
- Target UI ID still exists in rendered DOM.
- New UI IDs are listed in `surfaces.json` when stable.
- Root primitives are listed in `components.json`.
- Tests cover changed registry, inventory, or DOM behavior.
@@ -0,0 +1,45 @@
# Worker-Backed Feature Pattern
Use this when a feature performs slow, retryable, external, scheduled, browser-backed or resource-heavy work.
## Worker Required When
- Work may exceed normal request time.
- Work needs retries.
- Work calls unreliable external providers.
- Work performs browser automation.
- Work processes files, imports, exports or media.
- Work should continue after a user navigates away.
- Usage metering or cleanup must be reliable.
## Required Manifest Entries
The feature manifest must declare:
- `integration.workers.required`.
- Queue names from `packages/queue/src/names.ts`.
- Job names from `packages/queue/src/payloads.ts`.
- Notes about retries, idempotency and cleanup.
- API route or UI flow that enqueues the job.
- UAT checks for worker success and failure states.
## Implementation Rules
- API routes enqueue jobs and return job/status IDs for long-running work.
- Workers load secrets server-side from admin/platform configuration.
- Jobs must be scoped by tenant/user where applicable.
- Jobs should be idempotent or have explicit duplicate protection.
- Browser jobs must enforce admin-owned navigation policy.
- Failures should be visible to the initiating user or admin.
- AI/browser-backed features use `toolctrl.ai-chatbot` and `toolctrl.browser-automation` unless a manifest explicitly justifies a new queue.
## Browser-Backed Work
Browser-backed features require extra constraints:
- Domain allowlist/denylist.
- Timeout policy.
- Screenshot/artifact storage policy.
- Credential handling rules.
- Cleanup jobs for sessions and artifacts.
- Audit events for start, completion and failure.