generated from coulomb/repo-seed
tegwick
b9aebb42f1
SDK (@binect/js): - BinectClient with domain sub-clients (documents, sendings, accounts, attachments, invoices) - HTTP Basic Auth, native fetch only (no runtime dependencies) - TypeScript types matching Binect API vocabulary - Status predicates and polling helpers in helpers.ts - Structured error handling (BinectApiError, BinectAuthError) Explorer: - Standalone browser-based API explorer (explorer/index.html) - Interactive testing without code Tests: - Unit tests for client, types, errors, helpers, http - E2E tests for upload/delete and send/cancel workflows Also includes: - Architecture Decision Records (ADRs) - Example DIN 5008 letter PDFs for testing - API specification research notes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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)
|