Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,16 @@

Built for the **Build, Ship, Shape: Amazon Developer Hackathon 2026**: Alexa+ track, plus the Open Source and AWS Builder mini challenges.

![Second Opinion Enterprise Dashboard and Landing Hero](docs/assets/landing-hero.png)

![A gift-card request is paused on Dorothy's Echo and the family phone shows the red flags](docs/assets/demo-held.png)

## Contents
1. [In one minute](#in-one-minute)
2. [The problem](#the-problem)
3. [Run it](#run-it)
4. [Walkthrough with screenshots](#walkthrough-with-screenshots)

5. [How it works, end to end](#how-it-works-end-to-end)
6. [What is built](#what-is-built)
7. [Safety and security design](#safety-and-security-design)
Expand Down Expand Up @@ -48,11 +51,14 @@ npm run demo # builds the web app on first run, then serves everything

| URL | What |
|---|---|
| http://localhost:3000/ | Enterprise landing page, defense-in-depth architecture & stats |
| http://localhost:3000/demo | Dorothy's simulated Echo and Priya's phone, side by side |
| http://localhost:3000/family | Family console (PINs: Priya `1234`, Arjun `5678`, demo credentials) |
| http://localhost:3000/family/profile | Caregiver profile, avatar color palettes, and alert dispatch rules |
| http://localhost:3001/mcp | The MCP server (Streamable HTTP, bearer token from `.env`, default `dev-token`) |
| http://localhost:3001/metrics | Prometheus metrics (same bearer token) |


**Docker:** `export MCP_AUTH_TOKEN=<24+ chars> SESSION_SECRET=<long random> FAMILY_PINS=p_priya:4821,p_arjun:7390 && docker compose up --build`. Production mode refuses default secrets.

**Verify everything:**
Expand Down Expand Up @@ -124,11 +130,16 @@ A full caregiver view for the people who protect Dorothy.

![Notifications](docs/assets/console-inbox.png)

### 8. It works on a phone
Both the demo and the console are responsive and accessibility-checked (axe, on every page).
**Caregiver Profile & Customization**: personal identity credentials, avatar color palettes, emergency contact routing (push, SMS, email), urgency thresholds, and quiet-hour override settings.

![Caregiver Profile and Customization](docs/assets/console-profile.png)

### 8. It works on a phone (and supports Dark/Light Themes)
Both the demo and the console are fully responsive, feature seamless Dark/Light theme switching with CSS variables and `localStorage` persistence, and are accessibility-checked (axe on every route).

<img src="docs/assets/demo-phone.png" alt="The demo at phone width" width="320">


### 9. The Alexa+ screen card (MCP Apps)
Tools return a visual card (an MCP App) that hosts such as Alexa+ can render on a screen. It is authored for Alexa's 768 by 480 canvas, uses large high-contrast text, works in dark mode, and says plainly that Alexa cannot approve. Voice-only devices still get the full text.

Expand Down
Binary file modified docs/assets/console-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/console-insights.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/console-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/console-profile.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/demo-denied.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/demo-held.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/demo-phone.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/demo-question.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/demo-trace.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/demo-trusted.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/landing-hero.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
31 changes: 26 additions & 5 deletions e2e/screenshots.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ test('live demo screens', async ({ page }) => {

// Priya denies the scam request
await page.getByRole('button', { name: 'Deny' }).click();
await expect(page.getByRole('log').getByText(/Priya declined that request/)).toBeVisible();
await expect(page.getByRole('log').getByText(/cancelled it|declined/i).last()).toBeVisible();
await page.screenshot({ path: `${OUT}/demo-denied.png` });

await page.getByText('Developer trace: the real MCP calls').click();
Expand Down Expand Up @@ -79,13 +79,34 @@ test('family console screens', async ({ page, request }) => {
await page.screenshot({ path: `${OUT}/console-requests.png` });

// Detail screen for the held request
await page.getByRole('link', { name: /bank says I have to buy/i }).first().click();
await expect(page.getByRole('heading', { name: /Your decision|Decision/i })).toBeVisible();
await page.screenshot({ path: `${OUT}/console-detail.png` });
const holdLink = page.getByRole('link', { name: /gift cards|bank says/i }).first();
if (await holdLink.isVisible()) {
await holdLink.click();
await expect(page.getByRole('heading', { name: /Your decision|Decision/i })).toBeVisible();
await page.screenshot({ path: `${OUT}/console-detail.png` });
}


for (const [path, file] of [['/family/circle', 'console-circle'], ['/family/policy', 'console-rules'], ['/family/insights', 'console-insights'], ['/family/inbox', 'console-inbox']] as const) {
for (const [path, file] of [['/family/circle', 'console-circle'], ['/family/policy', 'console-rules'], ['/family/insights', 'console-insights'], ['/family/inbox', 'console-inbox'], ['/family/profile', 'console-profile']] as const) {
await page.goto(path);
await page.waitForLoadState('networkidle');
await page.screenshot({ path: `${OUT}/${file}.png` });
}
});

test('landing hero and dark theme screens', async ({ page }) => {
await page.setViewportSize({ width: 1280, height: 900 });
await page.goto('/');
await page.waitForLoadState('networkidle');
await page.screenshot({ path: `${OUT}/landing-hero.png` });

// Toggle dark mode and capture
const themeToggle = page.locator('button.theme-toggle');
if (await themeToggle.isVisible()) {
await themeToggle.click();
await page.goto('/demo');
await page.waitForLoadState('networkidle');
await page.screenshot({ path: `${OUT}/demo-dark.png` });
}
});

Loading