# Architecture Overview

> **Last Updated**: 2025-01-12  
> **Maintainer**: AI Agent

## System Summary

Filevine Document Viewer is a Chrome/Edge browser extension that enables legal professionals to browse, download, and view documents from their Filevine projects using specialized local viewers. The extension uses a hybrid authentication approach, piggybacking on active Filevine sessions to extract tokens and make API calls. Initial focus is on DICOM medical imaging files common in personal injury cases.

## Component Diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│                    Chrome Extension Runtime                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────┐ │
│  │   Popup     │    │  Content    │    │    Background           │ │
│  │   (UI)      │◄──►│  Script     │◄──►│    Service Worker       │ │
│  │             │    │             │    │                         │ │
│  │ • Project   │    │ • Session   │    │ • API calls             │ │
│  │   selector  │    │   detection │    │ • File downloads        │ │
│  │ • File      │    │ • Token     │    │ • Token management      │ │
│  │   browser   │    │   extraction│    │ • Download queue        │ │
│  │ • Viewer    │    │             │    │ • IndexedDB storage     │ │
│  │   launcher  │    │             │    │                         │ │
│  └─────────────┘    └─────────────┘    └─────────────────────────┘ │
│                                │                                    │
│                                ▼                                    │
│                    ┌───────────────────────┐                        │
│                    │    Filevine API       │                        │
│                    │  api.filevineapp.com  │                        │
│                    └───────────────────────┘                        │
│                                │                                    │
│                                ▼                                    │
│                    ┌───────────────────────┐                        │
│                    │   S3 Presigned URLs   │                        │
│                    │   (File Downloads)    │                        │
│                    └───────────────────────┘                        │
└─────────────────────────────────────────────────────────────────────┘
```

## Technology Stack

| Layer | Technology | Version | Purpose |
|-------|------------|---------|---------|
| Extension Platform | Chrome Extension MV3 | 3 | Browser extension framework |
| Background | Service Worker | ES Modules | Background processing |
| Content Scripts | Vanilla JavaScript | ES6+ | Page injection |
| UI | HTML/CSS/JS | Vanilla | Popup interface |
| Storage | IndexedDB | Native | File storage |
| Storage | chrome.storage.session | Native | Auth token storage |
| API Client | Fetch API | Native | HTTP requests |
| Viewers | HTML5 Canvas | Native | DICOM rendering (future: cornerstone.js) |

## Entry Points

| Entry Point | Location | Purpose |
|-------------|----------|---------|
| Background Service Worker | `src/background/index.js` | Entry point for background processing |
| Content Script | `src/content/index.js` | Injected into Filevine pages |
| Popup UI | `src/popup/popup.html` | Extension popup interface |
| DICOM Viewer | `src/viewers/dicom/viewer.html` | Specialized DICOM file viewer |

## Key Directories

```
filevine-plugin/
├── src/
│   ├── background/         # Service worker (runs in background)
│   │   ├── index.js        # Message routing and initialization
│   │   ├── auth.js         # Token management & validation
│   │   ├── api.js          # Filevine API client
│   │   └── downloads.js    # Download queue & IndexedDB storage
│   ├── content/            # Content scripts (injected into Filevine pages)
│   │   ├── index.js        # Entry point
│   │   ├── detector.js     # Session/page change detection
│   │   └── extractor.js    # Token extraction from page context
│   ├── popup/              # Extension popup UI
│   │   ├── popup.html      # Popup markup
│   │   ├── popup.css       # Popup styles
│   │   └── popup.js        # UI controller
│   ├── viewers/            # File viewer plugins
│   │   ├── registry.js     # Viewer registration system
│   │   └── dicom/          # DICOM viewer
│   │       └── viewer.html # DICOM viewer UI
│   └── lib/                # Shared utilities
│       └── constants.js    # API URLs, message types, constants
├── public/
│   └── icons/              # Extension icons
├── docs/
│   └── DESIGN.md           # Full design document
└── .ai/                    # AI agent documentation
```

## Key Patterns

| Pattern | Where Used | Why |
|---------|------------|-----|
| Singleton | Background services (auth, api, downloads) | Single instance across extension lifecycle |
| Message Passing | Popup ↔ Background ↔ Content | Chrome extension communication pattern |
| Hybrid Auth | Content script extracts, background uses | Leverages existing Filevine session |
| Queue Pattern | Download manager | Manages concurrent downloads with limits |
| Registry Pattern | Viewer registry | Extensible viewer system |
| Storage Abstraction | IndexedDB wrapper | File persistence |

## External Dependencies

| Service | Purpose | Required | Failure Impact |
|---------|---------|----------|----------------|
| Filevine API | Document/project data | Yes | Extension non-functional |
| Filevine Identity | OAuth token source | Yes | Cannot authenticate |
| AWS S3 | File downloads | Yes | Downloads fail |
| Chrome Extension APIs | Extension functionality | Yes | Extension non-functional |

## Environment Configuration

| Variable | Purpose | Default | Required |
|----------|---------|---------|----------|
| N/A | Extension uses hardcoded API URLs | — | N/A |

**Note**: This extension uses hardcoded API endpoints. Configuration is managed via `src/lib/constants.js`.

## Quick Commands

```bash
# Load extension in Chrome
# 1. Open chrome://extensions
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select filevine-plugin directory

# Development workflow
# 1. Make code changes
# 2. Reload extension in chrome://extensions
# 3. Test in Filevine

# Debug background worker
# chrome://extensions → Filevine Viewer → "service worker" link

# Debug content script
# Open DevTools on Filevine page → Console tab
```

## Related Documentation

- `SERVICES.md` — Detailed service catalog
- `DATA_FLOW.md` — Data flow diagrams for auth, downloads, viewers
- `DECISIONS.md` — Architecture Decision Records
- `TROUBLESHOOTING.md` — Common issues and solutions
- `../docs/DESIGN.md` — Full design specification
- `../README.md` — Quick start guide
