Platform Canonicals

Status: SUPERSEDED PLATFORM SNAPSHOT. The table counts, sidebar taxonomy
and storage/routing decisions below are retained for lineage only. Use
../architecture/ARCHITECTURE_LOCK.md
and
../architecture/CANONICAL_SPINE_SCHEMA_FOUNDATION.md.

Original status: CANONICAL
Scope: Single source of truth for IntegrateWise platform state, data model, routing, and execution rules.
Last Updated: 2026-07-25

---

1. Navigation Layer Mapping

IntegrateWise surfaces are organized into 7 canonical nav groups. Every sidebar item is a projection over the Spine, not a hardcoded page.

Group	Scope	Projection Filter
My Work	Personal	user_id = current_user, then workspace_id
Communications	Channel	Conversational Store unified, Spine entity-linked
Workspaces	Domain	Role × Department × Industry
Platform	Operational	Platform services and connectors
Administration	Tenant	Tenant control plane
Me	Personal	Profile, preferences, connected accounts
Navigation	System	Surface selector state

Decision (DECISION-NAV-01): The sidebar is not navigation. It is a role-aware surface selector. Every item renders a projection of the same Spine tables filtered by scope.

---

2. 14 Core Spine Tables

These are the canonical Account Intelligence tables. They are the only source of operational truth.

#	Table	Purpose	Key Fields
1	tenants	Platform tenants	id, name, plan, settings_json
2	workspaces	Tenant workspaces	id, tenant_id, name, department, industry
3	users	All platform users	id, tenant_id, email, role, rbac_roles
4	providers	External providers	id, name, type, auth_config_ref
5	applications	Client apps	id, tenant_id, name, client_id
6	connections	Provider connections	id, tenant_id, provider_id, status, credential_ref
7	connectors	Connector configs	id, tenant_id, provider_id, category, sync_direction
8	capabilities	Business capabilities	id, name, domain, workflow_steps_json
9	schemas	Connector schemas	id, connector_id, version, entity_name, fields_json
10	webhooks	Webhook endpoints	id, tenant_id, connector_id, event, endpoint, secret_ref
11	sync_jobs	Sync job state	id, tenant_id, connector_id, direction, status, last_sync_at
12	entities	Canonical entities	id, tenant_id, type, data_json, source_links
13	timelines	Entity event log	id, entity_id, actor_type, action, payload_json, occurred_at
14	knowledge	Documents and notes	id, tenant_id, entity_links, content, source_type

---

3. 7 Missing Platform Config Tables

Required for platform operations but not yet deployed.

#	Table	Purpose	Key Fields
1	memory	Memory substrate	id, tenant_id, scope, content, embedding_ref, confidence
2	policies	Governance policies	id, tenant_id, name, rules_json, status
3	approvals	Approval records	id, tenant_id, entity_id, actor_id, decision, reason
4	audits	Audit log	id, tenant_id, actor_id, action, target_type, target_id, before_json, after_json
5	signals	Risk and health signals	id, tenant_id, entity_id, signal_type, value, threshold, window_days
6	deployments	Deployment records	id, tenant_id, service, environment, commit_sha, url, status
7	settings	Tenant + platform settings	id, tenant_id, category, key, value_json

---

4. Evidence Tables

Atomic write + link guarantee. Every piece of intelligence traces back to its source.

Table	Purpose	Relationship
source_links	Raw source documents	entity_id → provenance
intelligence_evidence	AI-generated evidence	entity_id → evidence chain

Rule: A field is not considered trustworthy unless its source_links entry is non-null and its intelligence_evidence entry has an actor_type of system or human, not inference.

---

5. Routing Logic

Rule (DECISION-ROUTING-01): All Spine queries pass through the Projection Platform. No service reads from Spine tables directly except the Spine service itself.

Spine routing is multi-layered:

1. Identity: Who is the user? (users)
2. Tenant: What is the tenant scope? (workspaces.tenant_id)
3. Scope: Personal → user_id; Work → workspace_id; Department → department; Industry → industry
4. Role: Which columns/rows are visible? (rbac_roles + field-level permissions)
5. Connector: Which fields surface? (connector_installations + schemas version)
6. Cache: Redis hot state first, Postgres fallback, shaped projection returned

Decision (DECISION-ROUTING-02): Adding a connector changes views automatically. The connector writes new fields to the Spine. The Projection Platform detects the schema version event. On the next request, it rebuilds the projection for that tenant's role/department/industry combination. No manual view configuration is required.

---

6. SSOT Rules

Shared Environment Registry

All secrets, credentials, and configuration values flow through one central registry. There is no alternate source of truth for operational state.

Layer	Audience	Variable Prefix	Source
Public applications	End users + browsers	NEXT_PUBLIC_IW_*	Next.js env / Vercel edge
Internal services	Backend workers only	IW_*	Doppler → Cloudflare Secrets / Vercel env
Platform services	Workers, pipelines, spine	IW_* + service-specific	Cloudflare Secrets
Infrastructure	Provisioning only	TF_VAR_*, CLOUD_*	Terraform / Doppler

Rules:

1. Every secret has exactly one source. IW_* vars are owned by the platform; NEXT_PUBLIC_IW_* are public mirrors of non-sensitive platform state.
2. Every service receives only the secrets it consumes (least-privilege distribution).
3. Every credential entry stores rotation.policy and last_rotated.
4. Every config key resolves at startup and fails closed if missing in production.
5. No hardcoded defaults for production secrets.

---

7. Long-running and Event-driven Task Taxonomy

DECISION-TAXONOMY-01: Hermes categorizes all long-running and background tasks into 12 canonical categories. No category is a catch-all; every task maps to exactly one.

#	Category	Trigger	Examples
1	Automation	Time-based	Renewal risk scoring, customer health recalculation, executive summaries, SLA checks, invoice reconciliation, license utilization
2	Watch	Event-based	GitHub releases, Salesforce schema changes, HubSpot property changes, Cloudflare deployments, production incidents, documentation updates
3	Memory	Time + Event	Memory compaction, duplicate detection, entity merging, timeline rebuilding, embedding regeneration, knowledge graph updates, continuity validation
4	AI	Event + Time	Overnight account summaries, ticket clustering, meeting summarization, opportunity forecasting, churn prediction, next-best-action generation, knowledge synthesis
5	Integration	Time + Event	Full sync, incremental sync, webhook verification, OAuth validation, connector health checks, schema discovery, rate-limit monitoring
6	Infrastructure	Time-based	Worker health, queue depth monitoring, cache warming, database optimization, secret rotation checks, backup verification, storage cleanup
7	Governance	Event + Time	Approval reminders, policy drift detection, permission audits, access reviews, audit report generation, compliance validation
8	Security	Event + Time	Token expiration checks, secret exposure detection, failed login analysis, API key validation, certificate expiration, suspicious activity detection
9	Workspace	Event + Time	Refresh dashboards, update KPIs, refresh timelines, compute priorities, assign work, generate daily briefings
10	Agent	Event + Time	Evaluate completed plans, retry failed executions, clean execution history, optimize workflows, update capability cache, learn from execution outcomes
11	Marketplace	Event + Time	Discover new connector versions, validate installed connectors, update connector metadata, check marketplace health
12	Observability	Time-based	Aggregate metrics, trace analysis, error clustering, latency analysis, cost reporting, capacity forecasting

---

8. Task Management MCP

Service Design

DECISION-MCP-01: A dedicated Task Management MCP service owns task execution. Hermes does not execute tasks inline; it schedules or watches them, and the MCP handles runtime, retries, and lifecycle.

Hermes
    │
    ▼
Task Management MCP
    │
    ├── Scheduler        — cron + event-based dispatch
    ├── Event Watches    — real-time change filters
    ├── Workflow Engine  — multi-step task orchestration
    ├── Retry Manager    — exponential backoff + DLQ
    ├── Notifications    — completion / failure alerts
    ├── History          — execution audit trail
    ├── Dead Letter Queue— unrecoverable task capture
    └── Metrics          — task latency, error rate, throughput

Core Capabilities

Every capability is an MCP tool exposed as tasks.<action>.

tasks.create
tasks.schedule
tasks.watch
tasks.run
tasks.pause
tasks.resume
tasks.cancel
tasks.retry
tasks.history
tasks.logs
tasks.metrics

Execution Models

DECISION-MCP-02: The platform supports two execution models. Tasks are typed by model, not by ad-hoc config, so watch tasks cannot accidentally run on a cron timer and automation tasks cannot fire without a schedule.

Time-based

• Every hour
• Every day
• Every Monday
• First day of the month

Event-based

• GitHub push received
• Salesforce opportunity updated
• Slack message posted
• New customer onboarded
• OAuth connection revoked
• Cloudflare deployment completed

This lets Hermes respond to real operational events while still handling recurring maintenance, giving you a unified execution model for automation across the platform.

---

9. Adaptive Spine Boundaries

Decision (DECISION-BOUNDARY-01): The Projection Platform is the only surface that reads from the Spine. Nothing else does.

• Spine = truth. Raw Postgres + Redis hot state.
• Projection = view. Shaped by permissions, connector schema, and role/department/industry routing.
• Twin = per-object intelligence. Not a sidebar chat. Activates on a specific object, surfaces evidence, closes on navigation.

Sidebar = role-aware surface selector, not navigation. Every sidebar item is a projection over the same Spine tables.

---

10. Continuity Loop

Decision (DECISION-CONTINUITY-01): Every execution outcome feeds back into the platform regardless of success or failure.

10 stages:

1. Observe — ingest signals, events, and state changes
2. Orient — map to tenant, department, role, and entity context
3. Plan — select capabilities and execution paths
4. Execute — run through governed execution paths with approval gates
5. Learn — write outcomes to memory and timeline
6. Synthesize — update signals, health scores, and forecasts
7. Project — rebuild affected projections if schema changed
8. Notify — deliver alerts via channel preference
9. Audit — log every change to timelines + audits
10. Replay — support rollback and schema version recovery

---

This document is the canonical reference. All implementation must trace back to a decision defined here.