Track HiveGrid Cloud planning reference
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user