Skip to content

Commit 1c95869

Browse files
committed
Updates README
- Features: Updated Form Guidance and Feedback Loop from "planned" to descriptions of what's built. Added Government Dashboard. - Architecture: Added Form Guidance, Feedback, Dashboard API, Response Management to server diagram. Added Dashboard section. - Monorepo Structure: Added packages/dashboard/ and scripts/ - Tech Stack: Added Dashboard, split out Extension UI, added deployment info, test count - Development: Added dashboard dev command and packaging instructions
1 parent 9f5e51e commit 1c95869

1 file changed

Lines changed: 40 additions & 14 deletions

File tree

README.md

Lines changed: 40 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@ AI browser extension that takes real human inputs to personalize content, flag e
44

55
## Features
66

7-
- **Content Simplification** -- Rewrites web pages at a reading level you choose, adds plain-language tooltips for jargon, and adjusts font size, contrast, and motion (prototyped)
8-
- **Benefits Discovery** -- Matches your profile against federal benefit programs using a deterministic rules engine, then ranks and explains results in plain language via AI (prototyped)
9-
- **Highlight-to-Ask** -- Select any text on a page and ask Ivy to explain it (prototyped)
10-
- **Form Guidance** -- Step-by-step explanations for government forms (planned)
11-
- **Feedback Loop** -- Users provide natural language feedback on websites; aggregated insights can be supplied to site owners to improve accessibility (planned)
7+
- **Content Simplification** -- Rewrites web pages at a reading level you choose, adds plain-language tooltips for jargon, and adjusts font size, contrast, and motion
8+
- **Benefits Discovery** -- Matches your profile against federal benefit programs using a deterministic rules engine, then ranks and explains results in plain language via AI
9+
- **Highlight-to-Ask** -- Select any text on a page and ask Ivy to explain it in a centered dialog with markdown rendering. Responses are cached per URL so repeat queries are instant across all users
10+
- **Form Guidance** -- Detects form fields on any page, generates plain-language explanations via AI, and displays hover tooltips next to each field. Maps fields to vault types for future auto-fill
11+
- **Feedback Loop** -- Users leave anchored feedback on specific page elements via "Leave site feedback" on the highlight-ask dialog or the Feedback tab. AI categorizes comments (confusing language, missing info, accessibility, etc.) and stores them with CSS selector location data
12+
- **Government Dashboard** -- Web app for site owners showing aggregated user interactions per domain and page. Renders a proxied page preview with highlighted elements where users interacted. Shows Ivy's AI responses, commonly asked questions, and feedback category distribution. Site owners can edit Ivy's cached responses via API
1213

1314
## Wireframes
1415

@@ -102,10 +103,20 @@ Chrome Extension (WXT)
102103
▼ HTTPS
103104
Server (Node.js + Hono)
104105
├── AI Transform Pipeline (Claude API)
105-
├── Explain Endpoint
106-
└── Benefits Evaluation
107-
├── Deterministic Rules Engine (@ivy/benefits-engine)
108-
└── AI Ranking & Explanation (Claude Haiku)
106+
├── Explain Endpoint (with response caching)
107+
├── Form Guidance Endpoint
108+
├── Feedback + Categorization (Claude Haiku)
109+
├── Benefits Evaluation
110+
│ ├── Deterministic Rules Engine (@ivy/benefits-engine)
111+
│ └── AI Ranking & Explanation (Claude Haiku)
112+
└── Dashboard API
113+
├── Domain/page aggregation
114+
├── Page proxy for preview
115+
└── Response management
116+
117+
Dashboard (Vite + React)
118+
├── Domain Overview (page list, category chart, top questions)
119+
└── Page Detail (proxied page preview with element highlights, insights panel)
109120
```
110121

111122
## Monorepo Structure
@@ -116,7 +127,9 @@ ivy/
116127
│ ├── shared/ # Types, message protocol, encryption utils, constants
117128
│ ├── extension/ # WXT Chrome extension (MV3)
118129
│ ├── server/ # Node.js API server (Hono)
130+
│ ├── dashboard/ # Site owner dashboard (Vite + React)
119131
│ └── benefits-engine/ # Deterministic eligibility rules
132+
├── scripts/ # Version bump and packaging scripts
120133
├── .github/workflows/ # CI (build, test, typecheck)
121134
├── Dockerfile # Multi-stage production build for server
122135
├── turbo.json
@@ -128,13 +141,15 @@ ivy/
128141
| Layer | Technology |
129142
|-------|-----------|
130143
| Extension framework | [WXT](https://wxt.dev) (MV3, cross-browser) |
131-
| UI | React 19, Radix UI, Tailwind CSS 4 |
132-
| State management | Zustand (persisted to chrome.storage) |
144+
| Extension UI | React 19, Radix UI, Tailwind CSS 4, Zustand |
145+
| Dashboard | Vite, React 19, React Router, Tailwind CSS 4 |
133146
| Server | Node.js 22, Hono |
134-
| AI | Claude API via `@anthropic-ai/sdk` |
147+
| AI | Claude API via `@anthropic-ai/sdk` (Haiku for most tasks, Sonnet for translation) |
148+
| Benefits engine | Deterministic rules with AI ranking |
135149
| Monorepo | Turborepo, pnpm workspaces |
136-
| Testing | Vitest |
150+
| Testing | Vitest (180 tests) |
137151
| Client encryption | Web Crypto API (AES-256-GCM) |
152+
| Deployment | Railway (server), GitHub Actions (CI) |
138153

139154
## Getting Started
140155

@@ -157,18 +172,29 @@ cp .env.example .env.local
157172

158173
### Development
159174

160-
Run the server and extension in separate terminals:
175+
Run the server, extension, and dashboard in separate terminals:
161176

162177
```bash
163178
# Terminal 1: Start the API server (port 3001)
164179
pnpm --filter @ivy/server dev
165180

166181
# Terminal 2: Start the extension dev server (opens Chrome with extension loaded)
167182
pnpm --filter @ivy/extension dev
183+
184+
# Terminal 3: Start the dashboard dev server (port 5173)
185+
pnpm --filter @ivy/dashboard dev
168186
```
169187

170188
The extension dev server uses WXT's hot module replacement. The Chrome profile is stored in `packages/extension/.chrome-profile/` so your extension state persists across restarts.
171189

190+
### Package Extension for Testing
191+
192+
```bash
193+
# Bump version and build/zip the extension
194+
pnpm version:bump # patch by default, or: ./scripts/bump-version.sh minor
195+
pnpm package:extension # builds and zips to dist/ivy-extension-{version}.zip
196+
```
197+
172198
### Build
173199

174200
```bash

0 commit comments

Comments
 (0)