AMIGO Frontend Architecture & Maestro Integration Plan

Overview

A lightweight, modern frontend for AMIGO that demonstrates core functionality and integrates seamlessly with Maestro platform.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Maestro Platform UI                       │
│  (Main orchestration interface - existing)                  │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   │ Embedded Widget / iframe
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                   AMIGO Frontend (React)                     │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Persona    │  │   Memory     │  │    Draft     │     │
│  │   Profile    │  │   Browser    │  │  Generator   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │    Brief     │  │ Integration  │  │   Settings   │     │
│  │  Generator   │  │   Status     │  │              │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   │ REST API
                   ▼
┌─────────────────────────────────────────────────────────────┐
│              AMIGO Backend (FastAPI)                         │
│                  Port 3101                                   │
└─────────────────────────────────────────────────────────────┘

Technology Stack

Frontend

Framework: React 18+ with TypeScript
Build Tool: Vite (fast, modern)
UI Library: Tailwind CSS + shadcn/ui components
State Management: React Query (TanStack Query) for server state
Router: React Router v6
API Client: Axios with interceptors
Form Handling: React Hook Form + Zod validation
Date/Time: date-fns
Icons: Lucide React

Integration

Maestro SDK: Custom hook for platform integration
Authentication: JWT tokens passed from Maestro
Communication: PostMessage API for iframe communication

Project Structure

amigo-frontend/
├── public/
│   ├── favicon.ico
│   └── amigo-logo.svg
├── src/
│   ├── components/
│   │   ├── ui/              # shadcn/ui components
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── input.tsx
│   │   │   ├── textarea.tsx
│   │   │   ├── select.tsx
│   │   │   ├── dialog.tsx
│   │   │   └── toast.tsx
│   │   ├── layout/
│   │   │   ├── Header.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   └── Layout.tsx
│   │   ├── persona/
│   │   │   ├── PersonaCard.tsx
│   │   │   ├── PersonaEditor.tsx
│   │   │   └── ToneSelector.tsx
│   │   ├── memory/
│   │   │   ├── MemoryList.tsx
│   │   │   ├── MemoryCard.tsx
│   │   │   ├── MemorySearch.tsx
│   │   │   └── MemoryForm.tsx
│   │   ├── drafts/
│   │   │   ├── DraftGenerator.tsx
│   │   │   ├── DraftEditor.tsx
│   │   │   ├── DraftPreview.tsx
│   │   │   ├── PlatformSelector.tsx
│   │   │   └── DraftList.tsx
│   │   └── briefs/
│   │       ├── BriefGenerator.tsx
│   │       ├── BriefViewer.tsx
│   │       └── BriefExport.tsx
│   ├── lib/
│   │   ├── api/
│   │   │   ├── client.ts        # Axios instance
│   │   │   ├── auth.ts          # Auth endpoints
│   │   │   ├── memory.ts        # Memory endpoints
│   │   │   ├── drafts.ts        # Draft endpoints
│   │   │   ├── briefs.ts        # Brief endpoints
│   │   │   └── types.ts         # TypeScript types
│   │   ├── hooks/
│   │   │   ├── useAuth.ts
│   │   │   ├── useMemories.ts
│   │   │   ├── useDrafts.ts
│   │   │   ├── useBriefs.ts
│   │   │   └── useMaestro.ts    # Maestro integration
│   │   └── utils/
│   │       ├── format.ts
│   │       ├── validation.ts
│   │       └── storage.ts
│   ├── pages/
│   │   ├── Dashboard.tsx
│   │   ├── Persona.tsx
│   │   ├── Memories.tsx
│   │   ├── Drafts.tsx
│   │   ├── Briefs.tsx
│   │   └── Settings.tsx
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
└── README.md

Key Features

1. Dashboard (Landing Page)

Purpose: Overview of AMIGO activity and quick actions

Components:

Statistics cards (memories count, drafts generated, briefs created)
Recent activity feed
Quick action buttons
Persona profile summary

API Calls:

GET /amigo/v1/auth/me - Current user
GET /amigo/v1/memory/stats - Memory statistics
GET /amigo/v1/drafts/stats/summary - Draft statistics

2. Persona Profile

Purpose: Configure writing style and preferences

Components:

Tone selector (casual, professional, formal, friendly)
Verbosity slider (concise → balanced → detailed)
Formality slider (0 → 1)
Language selector
Timezone selector

API Calls:

GET /amigo/v1/auth/me - Get persona profile
PUT /amigo/v1/persona (to be implemented) - Update persona

3. Memory Browser

Purpose: View, search, and manage memories

Components:

Memory list with pagination
Search bar with filters (type, scope, importance)
Memory cards with preview
Add/Edit memory dialog
Delete confirmation

API Calls:

GET /amigo/v1/memory/ - List memories
POST /amigo/v1/memory/search - Search memories
POST /amigo/v1/memory/ - Create memory
PUT /amigo/v1/memory/{id} - Update memory
DELETE /amigo/v1/memory/{id} - Delete memory

4. Draft Generator

Purpose: Generate persona-aware communication drafts

Components:

Platform selector (email, Slack, Jira, GitHub)
Intent input (what you want to say)
Recipients field
Length selector (short, medium, long)
Include memories toggle
Generated draft preview
Edit/Regenerate/Approve actions

API Calls:

POST /amigo/v1/drafts/generate - Generate draft
PUT /amigo/v1/drafts/{id} - Update draft
DELETE /amigo/v1/drafts/{id} - Delete draft
GET /amigo/v1/drafts/ - List drafts

Flow:

User Input → Generate → Preview → Edit (optional) → Approve → Copy/Send

5. Brief Generator

Purpose: Generate communication briefs from context

Components:

Context input (what to summarize)
Scope selector (project, team, personal)
Tone selector
Max length input
Include memory toggle
Generated brief viewer
Section-by-section view
Export options (Markdown, Text)

API Calls:

POST /amigo/v1/briefs/generate - Generate brief
Export handled client-side

6. Settings

Purpose: Manage integrations and preferences

Components:

OAuth connector status
API key management
Notification preferences
Data retention settings

Maestro Integration

Integration Approach

AMIGO will be integrated into Maestro as:
1. Standalone Widget - Accessible from Maestro sidebar
2. Context Menu - Right-click actions in Maestro (e.g., "Generate draft from selection")
3. Command Palette - Quick actions via CMD+K in Maestro

Integration Interface

1. Maestro → AMIGO Communication

PostMessage API:

// From Maestro to AMIGO iframe
window.postMessage({
  type: 'MAESTRO_CONTEXT',
  payload: {
    selectedText: string,
    currentView: 'github' | 'jira' | 'calendar',
    authToken: string,
    userId: string,
    tenantId: string
  }
}, '*');

2. AMIGO → Maestro Communication

PostMessage API:

// From AMIGO to Maestro parent
parent.postMessage({
  type: 'AMIGO_ACTION',
  payload: {
    action: 'draft_generated' | 'memory_created',
    data: {...}
  }
}, '*');

Maestro Integration SDK

File: src/lib/hooks/useMaestro.ts

export interface MaestroContext {
  selectedText?: string;
  currentView?: string;
  authToken?: string;
  userId?: string;
  tenantId?: string;
}

export interface MaestroSDK {
  context: MaestroContext;
  sendDraft: (draft: Draft) => void;
  notifySuccess: (message: string) => void;
  notifyError: (error: string) => void;
  openInNew: (url: string) => void;
}

export function useMaestro(): MaestroSDK {
  // Implementation
}

API Integration Layer

API Client Setup

File: src/lib/api/client.ts

import axios from 'axios';

export const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_URL || 'local-service',
  headers: {
    'Content-Type': 'application/json',
  },
});

// Request interceptor - add auth token
apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem('amigo_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Response interceptor - handle errors
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Redirect to login or request new token from Maestro
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

TypeScript Types

File: src/lib/api/types.ts

// Generated from OpenAPI schema or manually defined
export interface Memory {
  id: string;
  user_id: string;
  tenant_id: string;
  memory_type: 'decision' | 'preference' | 'fact' | 'interaction';
  scope?: string;
  scope_id?: string;
  content: string;
  importance: number;
  source?: string;
  created_at: string;
  accessed_count: number;
  tags: string[];
}

export interface Draft {
  id: string;
  platform: 'email' | 'slack' | 'jira' | 'github' | 'generic';
  state: 'draft' | 'approved' | 'rejected' | 'sent';
  intent: string;
  content: string;
  subject?: string;
  recipients: string[];
  metadata: DraftMetadata;
  created_at: string;
  updated_at: string;
}

export interface Brief {
  id: string;
  context: string;
  sections: BriefSection[];
  summary: string;
  tone: string;
  word_count: number;
  memories_used: number;
  generated_at: string;
}

// ... other types

React Query Integration

Example: Memory Hooks

File: src/lib/hooks/useMemories.ts

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import * as memoryApi from '../api/memory';

export function useMemories(filters?: MemoryFilters) {
  return useQuery({
    queryKey: ['memories', filters],
    queryFn: () => memoryApi.listMemories(filters),
  });
}

export function useMemory(id: string) {
  return useQuery({
    queryKey: ['memories', id],
    queryFn: () => memoryApi.getMemory(id),
  });
}

export function useCreateMemory() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: memoryApi.createMemory,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['memories'] });
    },
  });
}

export function useUpdateMemory() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: MemoryUpdate }) =>
      memoryApi.updateMemory(id, data),
    onSuccess: (_, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['memories'] });
      queryClient.invalidateQueries({ queryKey: ['memories', id] });
    },
  });
}

UI Components (shadcn/ui)

Key Components Needed

1. Button - Primary, secondary, outline variants
2. Card - Container for memory/draft cards
3. Input - Text input with validation
4. Textarea - Multi-line text input
5. Select - Dropdown selector
6. Dialog - Modal for forms
7. Toast - Success/error notifications
8. Badge - Status indicators
9. Tabs - Navigation between sections
10. Spinner - Loading indicator

Environment Configuration

File: .env.example

# API Configuration
VITE_API_URL=local-service
VITE_API_TIMEOUT=30000

# Maestro Integration
VITE_MAESTRO_MODE=embedded
VITE_MAESTRO_PARENT_ORIGIN=local-service

# Features
VITE_ENABLE_DRAFTS=true
VITE_ENABLE_BRIEFS=true
VITE_ENABLE_MEMORY_SEARCH=true

# Debug
VITE_DEBUG=false

Development Setup

Installation

# Create frontend project
npm create vite@latest amigo-frontend -- --template react-ts
cd amigo-frontend

# Install dependencies
npm install react-router-dom axios @tanstack/react-query
npm install -D tailwindcss postcss autoprefixer
npm install lucide-react date-fns
npm install react-hook-form zod @hookform/resolvers

# Install shadcn/ui
npx shadcn-ui@latest init
npx shadcn-ui@latest add button card input textarea select dialog toast

Development Server

# Run frontend
npm run dev        # Port 5173

# Run backend (separate terminal)
cd ../amigo-service
poetry run uvicorn src.main:app --reload --port 3101

Deployment Strategy

Standalone Deployment

# Build frontend
npm run build

# Serve with nginx or similar
# Output: dist/

Maestro Embedded Deployment

# Build with Maestro integration
npm run build:maestro

# Deploy to Maestro CDN or serve as widget

Demo Flow (POC)

User Journey

1. Login (via Maestro auth token)
2. Dashboard - See overview
3. Persona Setup - Configure writing style
4. Create Memory - Add a few sample memories
5. Generate Draft - Create email draft from intent
6. View Draft - Preview generated content
7. Edit & Approve - Make tweaks, approve
8. Generate Brief - Create summary from context
9. Export Brief - Download as Markdown

Demo Data

Pre-populated sample data for quick demo:

5 sample memories (meetings, decisions, preferences)
2 draft templates
1 brief example

Timeline

Week 6: Frontend Foundation (5 days)

Day 1: Project setup, component library
Day 2: API client, routing, layout
Day 3: Dashboard, Persona pages
Day 4: Memory browser
Day 5: Basic styling, polish

Week 7: Core Features (5 days)

Day 1-2: Draft generator UI
Day 3: Brief generator UI
Day 4-5: Maestro integration layer

Week 8: Polish & Demo (3 days)

Day 1: Testing, bug fixes
Day 2: Demo flow, sample data
Day 3: Documentation, deployment

Success Metrics

Technical

✅ All API endpoints integrated
✅ Responsive design (mobile, tablet, desktop)
✅ <2s page load time
✅ Zero console errors
✅ TypeScript strict mode

User Experience

✅ Intuitive navigation
✅ Clear call-to-actions
✅ Helpful error messages
✅ Loading states
✅ Success confirmations

Integration

✅ Maestro iframe embedding
✅ PostMessage communication
✅ Auth token handling
✅ Context passing

Next Steps

1. ✅ Review and approve architecture
2. ✅ Set up frontend project structure
3. ✅ Implement API integration layer
4. ✅ Build core UI components
5. ✅ Create demo flow
6. ✅ Test Maestro integration
7. ✅ Deploy and demonstrate

Recommendation: Start with a lightweight, functional demo that demonstrates core AMIGO capabilities (persona, memory, drafts). Add polish and features incrementally based on feedback.

AMIGO Frontend Architecture & Maestro Integration Plan