Skip to main content

Research Hub Enterprise Architecture

Use when designing Research Hub enterprise SaaS.

Project location​

  • Repository: jknash/research-hub
  • Specification worktree: /root/Working/Worktrees/research-hub-next-spec
  • Branch: docs/next-revision-spec
  • Read CAPABILITY-MAP-next-revision.md, DESIGN-enterprise-saas.md, ADR-001-azure-topology.md, all 12 next-revision SPEC-*.md files, CONTRACTS-next-revision.md, and contracts/ before changing architecture.
  • Preserve old single-owner specs as migration evidence; do not silently treat them as the enterprise target.

Confirmed owner intent​

  • Deliver a production multitenant SaaS from the first release using a classic three-tier presentation/business/data separation.
  • Use Entra External ID with enterprise federation, including non-Microsoft IdPs; application data owns customer organizations, memberships, roles, and separation of duties.
  • Use Azure managed PaaS with Azure Container Apps, not AKS.
  • Use a shared data plane with enforced logical organization isolation.
  • Launch envelope: 10 organizations, 100 named users, 25 concurrent users, 100 research runs/day.
  • Use a zone-redundant primary Azure region plus warm secondary. Proposed workload SLO is 99.95%; RPO is at most 24 hours and end-to-end RTO is at most four hours including total primary-region loss. Treat these as objectives until drills qualify them.
  • Initial evidence sources: public web, bounded uploads, and production SharePoint/OneDrive connectors.
  • Project creation starts an agent-guided interview; a human explicitly confirms the immutable charter before acquisition or research.
  • Policy may auto-approve a report only to APPROVED_READY; an authorized natural person performs final publication. Full MCP workflow coverage uses identical authorization/policy/human gates.
  • Support only provider-supported commercial API/cloud/workload-federation or explicitly documented enterprise automation credentials. Consumer subscription OAuth is disabled. Tenant-connected credentials and an optional managed commercial plan are allowed, subject to provider terms.
  • Meter usage and enforce quotas now; billing/invoicing is later.
  • Target SOC 2/ISO control readiness and GDPR capabilities; HIPAA/FedRAMP are out of scope.

Non-negotiable design rules​

  • Use organization_id as the sole customer-isolation key. Entra tid is issuer provenance, not an application organization.
  • Name agent components by role; provider/model binding is configuration and immutable execution evidence, never domain policy or module identity.
  • Keep one business implementation behind REST, MCP, web, and workers.
  • Preserve the shared SINGLE_HUMAN / DUAL_CONTROL / STRICT separation matrix and authoritative internal subject_id plus organization membership_id.
  • Use PostgreSQL outbox/inbox plus Azure Queue Storage as selected in ADR-001; Service Bus requires a new costed ADR.
  • Fail closed on uncertain external effects, especially provider calls and publication.
  • Require joint PostgreSQL/Blob recovery watermarks, independent privacy-suppression evidence, and dual-region credential-version readiness before regional activation.

Specification workflow​

  • Follow gated spec-driven development: capability map → module specs/contracts → independent architecture/security/implementability reviews → owner approval → plan → tasks → implementation.
  • Reader findings are real gates. More than two failed correction rounds on the same contract require an independent Escalation Reviewer convergence plan before further ordinary patching.
  • Run python3 contracts/verify_contracts.py and git diff --check after contract edits. Treat parser/count success as necessary but not sufficient; re-run fresh-context reviewers on the exact commit.
  • Do not claim the specification approved while module files say draft or any independent reviewer returns REQUEST_CHANGES.

Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/research-hub-enterprise-architecture/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

Published by Muse · 2026-10-04.