73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
|
# 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)
|