# Marketing Agent Platform Overview

## Purpose

This document defines the target architecture for evolving the current Microsoft 365 custom engine agent into a multi-tenant marketing services platform. The platform is designed to combine private marketing expertise, customer-specific brand context, and role-aware orchestration in a chat-first experience.

## Product Goals

- provide a single chat interface for marketing service requests
- ground responses in private agency expertise and customer-approved materials
- isolate customer data by tenant, business unit, and role
- support multiple work modes including research, copy, design briefing, image generation, and video briefing
- preserve auditability for source context, model selection, and approval state

## Current Baseline

The current repository provides:

- a Microsoft 365 custom engine agent surface for Teams and Copilot
- a single inline system prompt in `src/agent.ts`
- `MemoryStorage` for transient state only
- Azure OpenAI configuration from environment variables

The current app is therefore a runtime shell that can host the planned platform, but it does not yet include retrieval, tenant isolation, prompt management, or workflow orchestration.

## Target Platform Layers

### Experience Layer

- `Teams` and `Microsoft 365 Copilot` remain the primary user interaction surfaces
- users authenticate through Microsoft identity
- the platform presents a chat-first workflow with follow-up questions, task confirmation, previews, and approval handoffs

### Identity And Access Layer

- resolve user identity with Microsoft Graph
- map the user to tenant, business unit, and organizational role
- derive context access rules and action permissions from that mapping

### Orchestration Layer

- classify the incoming request
- choose the response pattern, tools, and model family
- assemble the context package
- enforce retrieval and generation guardrails
- return a grounded response or a guided next step

### Context Layer

The context layer is split into three distinct pools:

1. `System context`
   - private agency playbooks, frameworks, service standards, and operating guidelines
2. `Customer approved context`
   - reusable brand rules, prior approved deliverables, and customer workflow rules
3. `Session generated context`
   - drafts and generated artifacts created during the current interaction that are not yet approved for long-term reuse

### Storage And Indexing Layer

- cached copies of Google Drive and Google Docs content
- chunk indexes and embeddings metadata
- tenant-scoped artifact metadata
- session state and approval state
- audit logs for prompt assembly and tool execution

### Integration Layer

- `Microsoft Graph` for user identity and role resolution
- `Google Drive` and `Google Docs` for source document retrieval
- future connectors for DAM, CMS, CRM, analytics, or creative tooling

## Proposed Repository Shape

The repository should evolve toward the following structure over time:

```text
apps/
  showcase-site/
docs/
  architecture/
src/
  channels/
  context/
    customer/
    system/
  domain/
  integrations/
  orchestration/
  prompts/
    customer/
    system/
  storage/
```

## Runtime Responsibilities

### `src/channels/`

- normalize inbound chat messages
- capture conversation metadata
- pass the request into orchestration

### `src/orchestration/`

- request classification
- model routing
- tool policy enforcement
- approval-aware workflow selection
- prompt package assembly

### `src/context/system/`

- fetch private agency expertise from Google sources
- normalize and cache long-lived reference material
- retrieve only the relevant expert slices for the active task

### `src/context/customer/`

- retrieve tenant-specific brand and campaign context
- separate approved content from session-only drafts
- enforce role-based inclusion rules

### `src/prompts/`

- store system prompt fragments, task policies, and customer prompt templates
- make prompt construction composable, versioned, and reviewable

### `src/storage/`

- persist session state
- track artifact approval status
- store cache metadata and retrieval provenance

## End-To-End Request Flow

```mermaid
flowchart TD
    user[CustomerUser] --> chat[TeamsOrCopilotChat]
    chat --> graph[MsGraphIdentity]
    graph --> roleMap[RoleTenantMapper]
    chat --> orchestrator[RequestOrchestrator]
    roleMap --> orchestrator

    orchestrator --> classifier[IntentClassifier]
    orchestrator --> promptAssembler[PromptAssembler]
    orchestrator --> modelRouter[ModelRouter]
    orchestrator --> toolPolicy[ToolPolicy]

    promptAssembler --> systemCtx[SystemContextRetrieval]
    promptAssembler --> customerCtx[CustomerContextRetrieval]
    promptAssembler --> sessionCtx[SessionGeneratedContext]

    systemCtx --> systemCache[SystemDocCache]
    customerCtx --> approvedAssets[ApprovedCustomerAssets]
    sessionCtx --> sessionStore[SessionStateStore]

    modelRouter --> textModel[TextModel]
    modelRouter --> imageModel[ImageModel]
    modelRouter --> researchModel[ResearchModel]
    modelRouter --> videoModel[VideoModel]

    toolPolicy --> allowedTools[AllowedTools]
    orchestrator --> response[GroundedResponse]
```

## Design Principles

- `Chat first`: the user should be able to start with natural language rather than navigating rigid workflows
- `Role aware`: identity should determine both visible context and permitted actions
- `Context before generation`: the system should retrieve relevant guidance before producing outputs
- `Approved by default`: only approved customer artifacts should become reusable future memory
- `Composable prompts`: instructions should be modular and reviewable, not hidden in one large string
- `Auditable outputs`: the platform should retain provenance for major decisions and generated work

## Initial Deliverables

The first implementation pass in this repository should produce:

- architecture documentation for the target platform
- prompt taxonomy and prompt package requirements
- retrieval and caching design for Google-backed content
- tenancy and role-mapping guidance for Microsoft Graph
- a phased implementation roadmap
- a showcase website for demonstrating the planned platform