# Nuclius Growth Module Architecture

Nuclius Growth is a first-class Nuclius module. It extends Nuclius Core rather than creating a
second orchestration, authorization, persistence, transport, or execution system.

## Current Capability Inventory

Nuclius Core currently provides:

- Strict TypeScript monorepo package boundaries.
- Tenant ownership tuple: `organization_id / user_id / workspace_id / project_id / session_id`.
- Deterministic session states for `plan`, `work`, `review`, and `autonomous` modes.
- Provider-neutral model adapter interfaces.
- Repository instruction discovery, context selection, controlled tools, patching, checkpoints,
  final diff inspection, and evidence reports.
- Deny-by-default policy evaluation before tool execution.
- Tool contracts for repository reads, search, git inspection, patching, shell execution, test
  running, approvals, and source-control delivery.
- Execution-plane scheduling, workspace allocation, leases, approvals, checkpoints, sandbox cleanup,
  and node quarantine primitives.
- Scoped in-memory persistence plus PostgreSQL migration tests for execution metadata.
- Cloudflare Command Center domain types, Access authentication, D1 persistence, Durable Objects,
  Queues, R2 artifacts, WebSocket events, and remote transport.
- Source-control delivery, GitHub App boundaries, provenance/SBOM helpers, usage governance,
  observability redaction, privacy/deletion controls, staging deployment controls, and CI gates.

## Reusable Components for Growth

Growth must consume these Core services:

- `@nuclius/domain` for ownership, roles, and permissions.
- `@nuclius/modules` for module registration and capability boundaries.
- `@nuclius/policy` for fail-closed execution decisions.
- `@nuclius/orchestration` for agentic planning/session execution.
- `@nuclius/model-adapters` for provider-neutral model access.
- `@nuclius/execution-plane` for scheduled work, approvals, checkpoints, leases, and cleanup.
- `@nuclius/artifact-service` for reports, briefs, exports, and generated marketing assets.
- `@nuclius/remote-transport` for authenticated node/Cloudflare communication.
- `@nuclius/usage-governance` for budget and quota enforcement.
- `@nuclius/observability` for redacted operational events.
- Command Center domain/UI surfaces for authenticated human review and approvals.

Growth must not recreate authentication, tenancy, model routing, queueing, artifacts, audit,
approvals, remote execution, sandboxing, or source-control delivery.

## Current Architectural Gaps

Milestone G1 intentionally leaves these as future work:

- Growth Workspace persistence and migrations.
- Business Profile, Brand Profile, Growth Objective, blueprint, playbook, lead, campaign,
  attribution, and experiment records.
- Growth context selection and typed memory.
- Growth-specific ProposedAction lifecycle and budget guard integration.
- Live read-only marketing integrations such as GA4 and Google Ads.
- Provider credential broker bindings.
- Live Growth agent runtime prompts/evaluations.
- Command Center interactive Growth screens.

## Module Architecture

`@nuclius/modules` defines the runtime-neutral module contract and registry. A module declares:

- capabilities
- agents
- tool grants
- policy requirements
- API route metadata
- navigation metadata
- boundary defaults

Registered modules consume Core services. They do not own Core services.

The default registry currently registers:

- `coding`: existing Nuclius coding-agent functionality.
- `growth`: the initial Nuclius Growth module shell.

## Growth Module Boundaries

Growth defaults are intentionally restrictive:

- credential access: `none`
- repository access: `none`
- external mutation access: `none`
- tools: none in G1

Growth agents are registered as metadata only in G1:

- Business Intelligence Agent
- Market Intelligence Agent
- Growth Strategist Agent

Later milestones may grant tools through explicit capabilities, policy, budget checks, approvals,
credential brokering, provider verification, checkpoints, artifacts, and audit events.

G3 implements local agent foundations for the same three Growth agents. These runners produce
deterministic briefs from tenant-scoped Growth Workspace bundles and explicit evidence inputs. They
do not invoke model providers, fetch marketing APIs, access repositories, use shell tools, or mutate
external systems.

G4 adds a GA4 read-only boundary that validates scoped property bindings, accepts secret-reference
names without credential values, builds bounded report requests, and normalizes already-fetched
GA4-like rows into tenant-scoped marketing entities with digest-only evidence. It still does not
perform OAuth, call Google APIs, or fetch live analytics data.

G5 adds a Google Ads read-only boundary that validates scoped customer bindings, accepts
secret-reference names without credential values, builds bounded report requests, normalizes
already-fetched campaign/ad group/ad rows into tenant-scoped marketing entities with digest-only
evidence, and produces advisory recommendations. It still does not perform OAuth, call Google Ads
APIs, change bids, change budgets, create ads, or mutate campaigns.

## Tenant Isolation Model

Every Growth object must remain scoped to:

```text
organization_id / user_id / workspace_id / project_id
```

Session-bound operations also include:

```text
session_id
```

Growth Workspaces should reuse the existing workspace boundary with module-specific metadata rather
than creating a parallel tenant model. Repository methods and persistence queries must require the
ownership context and fail closed on mismatch.

## Capability and Security Model

New Growth permissions are explicit:

- `growth:view`
- `growth:manage`
- `growth:objective:manage`
- `growth:integration:view`
- `growth:integration:manage`

Growth permissions do not imply repository or shell permissions. Coding permissions do not imply
marketing credential access. External marketing mutations must be represented as ProposedActions in
future milestones and must pass Core policy, authorization, deterministic budget checks, approval
evaluation, idempotency controls, provider state verification, checkpointing, artifact/evidence
recording, and audit logging.

Untrusted marketing data includes websites, CRM notes, lead text, email content, comments, uploaded
files, competitor pages, and provider output. It may inform analysis but cannot redefine policy,
permissions, budgets, credentials, approvals, or system instructions.

## Proposed Growth Domain Model

Milestone G2 introduces typed records for:

- Growth Workspace metadata
- Business Profile
- Brand Profile
- Growth Objective
- Customer Profile
- Offer
- Industry Blueprint
- Growth Playbook
- Campaign
- Lead
- Opportunity
- Customer
- Revenue Event
- Attribution Event
- Growth Experiment
- Growth Memory

The current G2/G3/G4 implementation includes Growth Workspace metadata, Business Profile, Brand
Profile, Growth Objective, Industry Blueprint, Growth Playbook, normalized marketing entities,
structured Growth agent briefs, and a read-only GA4 normalization boundary. Later milestones will
add lead/customer/revenue-specific records, attribution events, experiments, and typed Growth
memory. G5 adds Google Ads read-only normalization and advisory recommendations. All records and
briefs must carry tenant ownership and provenance.

## Blueprint and Playbook Model

Blueprints define reusable industry defaults:

- objectives
- channels
- customer segments
- lead qualification fields
- CRM stages
- KPIs
- recommended integrations
- risks and compliance notes
- policy suggestions

Playbooks define reusable growth strategies:

- required agent capabilities
- stages
- KPIs
- recommended channels
- required integrations
- action policies
- optimization strategy

Blueprints and playbooks provide defaults and must not prevent company-specific customization.

## Milestone Plan

- G1: module framework, Coding/Growth registration, Command Center module navigation.
- G2: Growth domain foundation and tenant-scoped persistence.
- G3: Business Intelligence, Market Intelligence, and Growth Strategist agent foundation.
- G4: GA4 read-only normalization and evidence capture boundary.
- G5: Google Ads read-only normalization and recommendations.
- G6: leads, customers, revenue, and attribution.
- G7: Growth ProposedAction and approval lifecycle.
- G8: narrow controlled Google Ads mutations.
- G9: observe/analyze/recommend/propose/approve/execute/measure optimization loop.
- G10: duplicatable onboarding across multiple example companies without code changes.

## Risks and Migration Concerns

- Growth can spend real money; budget checks must be deterministic and fail closed.
- External marketing data increases prompt-injection exposure.
- Provider APIs can return ambiguous state; Growth must not assume mutation success.
- Growth UI must not display fabricated metrics or imply live integrations before they exist.
- Module permissions must not broaden existing coding-agent access.
- Persistence migrations must preserve existing execution-plane and Command Center contracts.
- Agent brief summaries must redact secrets and treat unmatched external content as untrusted
  context, not trusted instructions.