# Architecture Visualizations - Decision-Focused Sequence Charts

This appendix is intentionally narrow. It focuses on the five sequences that matter most to Jay's decision about whether M0-M1 is worth approving.

The charts below align to the current proposal and technical plan:

- M0-M1 is the first commitment.
- "Today at APEX" is the first product surface.
- The first operating posture is read-first, write-later.
- Brokermint exception review is the first controlled workflow.
- Every milestone must produce a usable deliverable and a clear go / pivot / stop decision.

## 1. M0 Discovery To M1 Scope Lock

```mermaid
sequenceDiagram
    autonumber
    actor Jay
    participant PL as Product Lead
    participant EL as Engineering Lead
    participant Team as APEX Staff
    participant Systems as Source Systems
    participant Scope as M1 Scope Pack

    Jay->>PL: Approve M0 discovery sprint
    PL->>Team: Interview workflow owners
    Team-->>PL: Current process, pain points, exceptions
    PL->>EL: Prioritize first pilot workflow
    EL->>Systems: Validate API, export, sandbox, and access paths
    Systems-->>EL: Capability limits, blockers, sample data options
    PL->>EL: Define source-of-truth map and approval rules
    EL-->>PL: Data model, architecture plan, risk notes
    PL->>Team: Review wireframe and baseline metrics
    Team-->>PL: Feedback on trust, usability, and priority
    PL->>Scope: Finalize M1 acceptance criteria and fixed scope
    Scope-->>Jay: Go / pivot / stop recommendation for M1
```

## 2. Daily Operations Review In Today At APEX

```mermaid
sequenceDiagram
    autonumber
    actor Ops as Operations Lead
    participant UI as Today at APEX UI
    participant Status as DashboardStatusService
    participant Runs as WorkflowRunService
    participant Adapters as IntegrationAdapterService
    participant Broker as Brokermint
    participant ReChat as ReChat
    participant Xara as Xara Cloud
    participant AdWorks as AdWorks
    participant CRM as Twenty / CRM Layer

    Ops->>UI: Open daily command center
    UI->>Status: Request exceptions, approvals, owners, next actions
    Status->>Runs: Load workflow states and approval queue
    Status->>Adapters: Refresh source-system summaries
    Adapters->>Broker: Read transaction file status
    Adapters->>ReChat: Read contact / communication signals
    Adapters->>Xara: Read asset status
    Adapters->>AdWorks: Read campaign prep status
    Adapters->>CRM: Read contact and task status
    Broker-->>Adapters: Current file data
    ReChat-->>Adapters: Current relationship data
    Xara-->>Adapters: Current asset data
    AdWorks-->>Adapters: Current campaign data
    CRM-->>Adapters: Current CRM data
    Adapters-->>Status: Source data plus sync timestamps
    Runs-->>Status: Workflow state, approvals, audit context
    Status-->>UI: Confirmed / inferred / stale statuses with owners
    UI-->>Ops: Exceptions-first daily view
```

## 3. Controlled Brokermint Exception Review (M1 Core Workflow)

```mermaid
sequenceDiagram
    autonumber
    actor Ops as Operations Reviewer
    participant UI as Today at APEX UI
    participant Orch as OrchestratorService
    participant Flow as Brokermint Exception Workflow
    participant Adapter as Brokermint Adapter
    participant Policy as Context / Policy Files
    participant Approval as ApprovalService
    participant Audit as AuditLogService

    Ops->>UI: Start or open Brokermint exception review
    UI->>Orch: Trigger controlled workflow run
    Orch->>Policy: Load compliance rules and approval policy
    Orch->>Flow: Start workflow with scoped inputs
    Flow->>Adapter: Read file status using sample, sandbox, export, or read-only data
    Adapter-->>Flow: Missing items, deadlines, metadata, sync time
    Flow->>Flow: Classify exceptions and draft next actions
    Flow->>Audit: Record evidence, steps, and recommendations
    Flow->>Approval: Queue any action that needs human sign-off
    Approval-->>Ops: Show exception summary and approval request
    Ops-->>Approval: Approve, reject, or request correction
    Approval-->>Audit: Record decision and comments
    Audit-->>UI: Update workflow result and visible audit trail
```

## 4. Approval Queue And Execution Release

```mermaid
sequenceDiagram
    autonumber
    participant Flow as Workflow
    participant Approval as ApprovalService
    actor Reviewer as Authorized Reviewer
    participant Perms as PermissionsService
    participant Action as Action Executor
    participant Audit as AuditLogService

    Flow->>Approval: Submit action with risk tier and evidence
    Approval->>Perms: Validate reviewer role and action type
    Perms-->>Approval: Allowed reviewer set
    Approval-->>Reviewer: Present action, source data, and impact

    alt Approved
        Reviewer->>Approval: Approve with comment
        Approval->>Action: Release permitted action
        Action-->>Approval: Execution result
        Approval->>Audit: Record approval and outcome
    else Rejected
        Reviewer->>Approval: Reject with reason
        Approval->>Audit: Record rejection and next step
    else Needs Revision
        Reviewer->>Approval: Return for correction
        Approval->>Audit: Record revision request
    end
```

## 5. Milestone Decision Gate Sequence

```mermaid
sequenceDiagram
    autonumber
    actor Jay
    participant Team as APEX Review Team
    participant Build as Build Team
    participant Metrics as Baseline / Pilot Metrics
    participant Memo as Decision Memo

    Build->>Team: Deliver milestone output for use, test, and review
    Team->>Metrics: Compare results against baseline and acceptance criteria
    Metrics-->>Team: Time saved, trust level, blockers, adoption, accuracy
    Team->>Memo: Summarize what worked, what failed, and what changed
    Memo-->>Jay: Recommend go, pivot, stop, or rescope

    alt Go
        Jay->>Build: Fund next milestone
    else Pivot
        Jay->>Build: Adjust workflow, scope, or source-system target
    else Stop
        Jay->>Build: End roadmap after usable deliverable
    end
```