generated from coulomb/repo-seed
Add Binect SDK implementation, Explorer, and test suite
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>
This commit is contained in:
72
architecture/ADR-003-explorer-architecture.md
Normal file
72
architecture/ADR-003-explorer-architecture.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user