# ADR-003: Explorer Architecture

## Status
Accepted

## Context
The Binect Explorer needs to be a browser-based interactive tool for:
- Learning the Binect API
- Experimentation and evaluation
- Safe testing before production integration

Per the TSD (Section 4), the Explorer:
- Must operate without server-side components
- Must clearly distinguish between preview and send operations
- Must require explicit confirmation for destructive actions
- Is a learning tool, not an operations dashboard

## Decision

### 1. Technology Stack
We use a **vanilla JavaScript/HTML/CSS** approach:
- No framework dependencies (React, Vue, etc.)
- Single HTML file with embedded CSS and JS
- Can use the SDK directly via module import
- Easy to host as a static file

Rationale: Per TSD Section 7, the product must remain independent of specific UI frameworks. A vanilla approach ensures maximum portability and simplicity.

### 2. Architecture Pattern
**Component-based with vanilla JS**:
- Modular JavaScript functions for each feature
- Event-driven UI updates
- State management via simple objects

### 3. Feature Organization
The Explorer UI is organized around the API domains:
- **Credentials Panel**: Input and manage API credentials
- **Documents Panel**: Upload, view, manage documents
- **Sendings Panel**: Announce and track mail dispatch
- **Attachments Panel**: Manage attachments
- **Account Panel**: View account info and options

### 4. Safety Features
Per TSD requirements:
- Credentials are ephemeral by default (cleared on page refresh)
- Optional local storage for convenience (opt-in)
- Send operations require explicit confirmation dialog
- Preview available before sending
- Clear visual distinction between safe (read) and destructive (send/delete) actions

### 5. Use Case Profiles
- Stored in browser localStorage
- Export/import as JSON files
- Contain only parameter configurations, not workflows

## Consequences

### Positive
- Zero external dependencies
- Works as single HTML file
- Easy to understand and modify
- Can be hosted anywhere (CDN, local file, etc.)
- Aligns with TSD requirement for framework independence

### Negative
- Less sophisticated UI compared to framework-based apps
- Manual DOM manipulation
- No virtual DOM or reactive updates

## References
- TSD: Section 4 (Explorer Technical Orientation)
- PRD: Section 4.1 (Functional Expectations)