Technical Documentation · Architecture Reference · Operational Runbooks
Institutional-grade document infrastructure for capital markets. Every document fingerprinted. Every action ledgered. Every signature legally binding.
Color Legend: 🔵 Core Engine · 🟡 Signing & Sessions · 🟣 Secure Documents · 🔴 Telecom & AI · 🟠 Perimeter · ⚫ Ledger & Storage · ⚙️ Operations · 🟢 Governance · 🏛 Capital
| # | Section | Layer | Status |
|---|---|---|---|
| 1 | Why This Exists for Capital Operations | 🏛 Capital | ✅ |
| 2 | System Architecture | Overview | ✅ |
| 3 | Module Registry | All Layers | ✅ |
| 4 | Data Flow Pipeline | 🔵 Core | ✅ |
| 5 | Signing & Distribution | 🟡 Gateway | ✅ |
| 6 | Secure Document Control | 🟣 SDC | ✅ |
| 7 | Telecom & AI Agent | 🔴 SCA | ✅ |
| 8 | Perimeter Security | 🟠 Cloudflare | ✅ |
| 9 | Ledger & Storage Systems | ⚫ Infra | ✅ |
| 10 | Security Model | All Layers | ✅ |
| 11 | Governance Model | 🟢 DAO | ✅ |
| 12 | Operations & Monitoring | ⚙️ Ops | ✅ |
| 13 | Deployment Reference | ⚙️ Ops | ✅ |
| 14 | System Invariants | 🏛 Capital | ✅ |
| 15 | Threat Model | 🔐 Security | ✅ |
| 16 | File Manifest | Reference | ✅ |
| 17 | Dependency Graph | Reference | ✅ |
| 18 | Quick Links | Navigation | ✅ |
| Document | Description | Path |
|---|---|---|
| Architecture Overview | Full system architecture with layer diagrams | architecture/ |
| Data Pipeline Flow | Ingest → Parse → Transform → Export → Sign → Anchor | flowcharts/ |
| Signing Flow | Multi-party signing ceremony flow | flowcharts/ |
| Telecom Flow | SMS/Voice → AI Intent → Action Engine → Response | flowcharts/ |
| Perimeter Flow | Edge → Tunnel → Webhook → Rate Limit → Service | flowcharts/ |
| SDC Flow | Token → Viewer → Watermark → Access Ledger | flowcharts/ |
| Module: Ingest | Format detection, PDF/DOCX/HTML/Image parsing | modules/ |
| Module: Parser | Section extraction, structural analysis | modules/ |
| Module: Transform | Governance, compliance, brand layers | modules/ |
| Module: Export | Multi-format output (JSON, HTML, PDF, MD, XML) | modules/ |
| Module: Signature | Digital signing, certificate generation | modules/ |
| Module: Gateway | Sessions, OTP, distribution, intent logging | modules/ |
| Module: SDC | Secure viewer, watermark, access tokens | modules/ |
| Module: Telecom | Telnyx integration, AI intent, action engine | modules/ |
| Module: Perimeter | Cloudflare config, tunnel, rate limiting | modules/ |
| Module: Sovereign | IPFS, CID registry, backup, monitoring | modules/ |
| Security Model | Zero trust layers, encryption, forensics | security/ |
| Security Controls | Network, application, crypto, operational controls | security/ |
| Governance Tiers | Tier 0/1/2 governance model | governance/ |
| Operations Runbook | Backup, monitoring, Docker, health checks | operations/ |
| Deployment Guide | Prerequisites, Docker Compose, environment config | operations/ |
| Threat Model | Attack surfaces, blast radius, failure containment | security/ |
| Visual Architecture | Single-page institutional architecture diagram | assets/ |
This system was not built to process documents. It was built to protect capital through document discipline.
Every capability maps to a fiduciary requirement:
| Capability | Capital Alignment | Risk Eliminated |
|---|---|---|
| Document Fingerprinting | Document integrity = capital integrity | Tampered records, fraudulent filings |
| Signing Ceremony | Signing discipline = legal defensibility | Disputed signatures, repudiation |
| Secure Document Control | Controlled viewing = information asymmetry control | Unauthorized disclosure, data leaks |
| 3-Tier Governance | Governance tiers = fiduciary alignment | Unauthorized commitments, rogue actions |
| Immutable Ledger | Ledger auditability = allocator visibility | Hidden modifications, lost audit trails |
| Perimeter Security | Edge defense = operational continuity | Service disruption, unauthorized access |
| Forensic Watermarking | Leak tracing = accountability enforcement | Anonymous document leaks |
| IPFS Anchoring | Content-addressing = permanent verifiability | Evidence destruction, revisionist claims |
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ INSTITUTIONAL OPERATORS │
│ ├── Fund administrators requiring auditable document trails │
│ ├── Capital allocators demanding fiduciary-grade controls │
│ ├── SPV managers needing sovereign document operations │
│ ├── Compliance officers requiring immutable governance records │
│ └── Legal teams requiring ESIGN/UETA-compliant signing ceremonies │
│ │
│ SOVEREIGN ENTITIES │
│ ├── RWA deal structuring with document-linked asset integrity │
│ ├── Telecom contract management with AI-assisted intake │
│ ├── Investor onboarding with controlled document distribution │
│ └── Multi-entity operations (fthco.com, OPTKAS SPVs, sovereign rails)│
│ │
└─────────────────────────────────────────────────────────────────────────┘
This is not a documentation library. This is a capital operations control system.
╔══════════════════════════════════════════════════════════════════════════════╗
║ EXTERNAL BOUNDARY ║
║ ║
║ 👤 Investor Device ──→ 📱 Telnyx SMS/Voice ──→ 🛡️ Cloudflare Edge ║
║ +1-844-669-6333 Zero Trust + WAF ║
║ │ ║
║ 🔒 Cloudflare Tunnel ║
║ (No Exposed Ports) ║
╚══════════════════════════════════╦═══════════════════════════════════════════╝
║
╔══════════════════════════════════╩═══════════════════════════════════════════╗
║ APPLICATION LAYER ║
║ ║
║ ┌─────────────────┐ ┌─────────────────────┐ ┌──────────────────────┐ ║
║ │ 🔴 SCA LAYER │ │ 🔵 DOCUMENT ENGINE │ │ 🟣 SDC LAYER │ ║
║ │ │ │ │ │ │ ║
║ │ Inbound Router │ │ Ingest (5 files) │ │ Secure Viewer │ ║
║ │ AI Intent Eng. │ │ Parser (4 files) │ │ Watermark Engine │ ║
║ │ Action Engine │ │ Transform (4 files) │ │ Forensic Fingerprint │ ║
║ │ Response Comp. │ │ Export (4 files) │ │ Access Tokens │ ║
║ │ Conv. Ledger │ │ Schema (4 files) │ │ Export Policy │ ║
║ │ Telecom Reg. │ │ Signature (4 files) │ │ Access Ledger │ ║
║ │ │ │ Research (7 files) │ │ Document Intake │ ║
║ │ Port: 3004 │ │ │ │ │ ║
║ │ 6 modules │ │ CLI: app.ts │ │ Port: 3003 │ ║
║ └─────────────────┘ └──────────┬──────────┘ │ 7 modules │ ║
║ │ └──────────────────────┘ ║
║ ┌─────────────────┐ ┌──────────┴──────────┐ ┌──────────────────────┐ ║
║ │ 🟡 SIGNING │ │ 🟠 PERIMETER │ │ ⚫ LEDGER SYSTEMS │ ║
║ │ GATEWAY │ │ │ │ │ ║
║ │ │ │ Cloudflare Config │ │ Lifecycle Registry │ ║
║ │ Signing Session │ │ Tunnel Manager │ │ CID Registry (IPFS) │ ║
║ │ OTP Engine │ │ Webhook Validator │ │ Ledger Anchor │ ║
║ │ Distribution │ │ Rate Limiter │ │ Backup Ledger │ ║
║ │ Intent Logger │ │ Perimeter Ledger │ │ Event Logs │ ║
║ │ │ │ │ │ │ ║
║ │ Port: 3002 │ │ 5 modules │ │ 3 registry modules │ ║
║ │ 4 modules │ └─────────────────────┘ │ 1 IPFS module │ ║
║ └─────────────────┘ └──────────────────────┘ ║
║ ║
║ ┌──────────────────────────────────────────────────────────────────────┐ ║
║ │ ⚙️ OPERATIONS INFRASTRUCTURE │ ║
║ │ │ ║
║ │ Backup Agent (AES-256-GCM) │ Monitor Dashboard (Port 3005) │ ║
║ │ Docker Compose (4 services) │ IPFS/Kubo Node (8081) │ ║
║ │ Batch Processor + Watcher │ Web Portal (3001) + Sovereign Portal │ ║
║ └──────────────────────────────────────────────────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════════════════════╝
| Module | Path | Files | Purpose |
|---|---|---|---|
| Ingest | ingest/ |
5 | Format detection · PDF · DOCX · HTML · Image (Tesseract OCR) |
| Parser | parser/ |
4 | Layout detection · Section extraction · Structure tagging · Canonicalization |
| Transform | transform/ |
4 | Governance layer · Compliance layer · Brand styling · Template composition |
| Export | export/ |
4 | HTML · JSON · PDF (Puppeteer) · Document exporter orchestration |
| Schema | schema/ |
4 | Document schema · Compliance schema · DAO schema · Research schema |
| Signature | signature/ |
4 | Fingerprint engine · Signing engine · QR generator · Signature state |
| Research | research/ |
7 | Research OS layer · Publication pipeline · Peer review · Proposal engine · Research schema · Registry · Style guide |
| Module | Path | Files | Purpose |
|---|---|---|---|
| Signing Session | gateway/signingSession.ts |
1 | Multi-party session management · Signer tracking · Status lifecycle |
| OTP Engine | gateway/otpEngine.ts |
1 | One-time password generation · Challenge verification · Expiry enforcement |
| Distribution | gateway/distributionEngine.ts |
1 | Multi-channel delivery (Email/SMS/WhatsApp/Telegram/QR) · Nodemailer SMTP |
| Intent Logger | gateway/intentLogger.ts |
1 | Signer intent capture · Legal compliance logging · ESIGN/UETA records |
| Module | Path | Files | Purpose |
|---|---|---|---|
| Secure Viewer | sdc/secureViewer.ts |
1 | Token-gated document rendering · View tracking |
| Watermark Engine | sdc/watermarkEngine.ts |
1 | Per-recipient forensic watermarking · Invisible marks |
| Forensic Fingerprint | sdc/forensicFingerprint.ts |
1 | Document forensics · Tamper detection · Chain of custody |
| Access Token Service | sdc/accessTokenService.ts |
1 | Time-limited single-use tokens · Revocation |
| Export Policy Engine | sdc/exportPolicyEngine.ts |
1 | Per-document export restrictions · Print/download controls |
| Access Ledger | sdc/accessLedger.ts |
1 | Hash-chained viewer access log · Audit trail |
| Document Intake | sdc/documentIntakeEngine.ts |
1 | Intake registration · SDC pipeline entry |
| Module | Path | Files | Purpose |
|---|---|---|---|
| Inbound Router | telecom/inboundRouter.ts |
1 | SMS/Voice webhook routing · Telnyx integration |
| AI Intent Engine | telecom/aiIntentEngine.ts |
1 | Natural language intent classification · Command extraction |
| Action Engine | telecom/actionEngine.ts |
1 | Intent → Action mapping · Governance tier enforcement |
| Response Composer | telecom/responseComposer.ts |
1 | AI-generated response formatting · Multi-channel output |
| Conversation Ledger | telecom/conversationLedger.ts |
1 | Hash-chained conversation history · Compliance archive |
| Telecom Registry | telecom/telecomRegistry.ts |
1 | Caller registration · Identity mapping · Permission levels |
| Module | Path | Files | Purpose |
|---|---|---|---|
| Cloudflare Config | perimeter/cloudflareConfig.ts |
1 | Zero Trust access policies · DNS configuration |
| Tunnel Manager | perimeter/tunnelManager.ts |
1 | Cloudflare Tunnel lifecycle · Route management |
| Webhook Validator | perimeter/webhookValidator.ts |
1 | HMAC webhook signature verification · Replay protection |
| Rate Limiter | perimeter/rateLimiter.ts |
1 | Per-IP sliding window · Burst protection · Auto-block |
| Perimeter Ledger | perimeter/perimeterLedger.ts |
1 | Security event log · Block/allow decisions · Audit trail |
| Module | Path | Files | Purpose |
|---|---|---|---|
| Lifecycle Registry | registry/lifecycleRegistry.ts |
1 | Document version tracking · State machine · History |
| CID Registry | registry/cidRegistry.ts |
1 | IPFS Content-ID tracking · Pin management |
| SKU Engine | registry/skuEngine.ts |
1 | Deterministic document SKU generation · Catalog |
| IPFS Client | ipfs/ipfsClient.ts |
1 | Kubo API integration · Add/Cat/Pin operations |
| Module | Path | Files | Purpose |
|---|---|---|---|
| Backup Agent | sovereign/backupAgent.ts |
1 | Encrypted incremental backups · AES-256-GCM · Retention policy |
| Monitor Dashboard | sovereign/monitorDashboard.ts |
1 | Real-time health monitoring · 9 subsystem checks · Port 3005 |
| Ledger Anchor | sovereign/ledgerAnchor.ts |
1 | Blockchain anchoring · Timestamp proofs |
| Ledger Adapter | sovereign/ledgerAdapter.ts |
1 | Multi-chain abstraction · Ethereum/Polygon/Local |
| Canonicalizer | sovereign/canonicalizer.ts |
1 | Deterministic document normalization |
| Document Fingerprint | sovereign/documentFingerprint.ts |
1 | SHA-256 canonical hashing · Merkle trees |
| Signing Engine | sovereign/signingEngine.ts |
1 | Cryptographic signing operations |
| QR Generator | sovereign/qrGenerator.ts |
1 | QR code generation for documents/sessions |
| Event Log | sovereign/eventLog.ts |
1 | Global hash-chained event journal |
| Audit Trail | sovereign/auditTrail.ts |
1 | Compliance audit trail aggregation |
| Module | Path | Files | Purpose |
|---|---|---|---|
| DAO Config | governance/daoConfig.ts |
1 | Governance rules · Tier definitions · Approval thresholds |
| Compliance Checker | governance/complianceChecker.ts |
1 | Regulatory compliance validation · Jurisdiction mapping |
| Governance Engine | governance/governanceEngine.ts |
1 | Governance overlay application · Policy enforcement |
| Agreement State | agreements/agreementStateEngine.ts |
1 | Agreement lifecycle · State transitions |
| Agreement Schema | agreements/agreementSchema.ts |
1 | Agreement data structures · Validation |
╔═══════════════════════════════════════════════════════════════════════════╗
║ SOVEREIGN DOCUMENT PIPELINE v4.0.0 ║
╠═══════════════════════════════════════════════════════════════════════════╣
║ ║
║ 📄 INPUT ║
║ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ ║
║ │ .pdf │ .docx │ .html │ .png │ .txt │ .md │ ║
║ └────┬────┴────┬────┴────┬────┴────┬────┴────┬────┴────┬────┘ ║
║ └─────────┴─────────┴────┬────┴─────────┴─────────┘ ║
║ │ ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 1: INGEST 🔵 Core │ ║
║ │ ┌───────────────┐ │ ║
║ │ │ Format Detect │──→ Route to correct parser │ ║
║ │ │ (detector.ts) │ PDF: pdf-parse │ ║
║ │ └───────────────┘ DOCX: mammoth │ ║
║ │ HTML: cheerio │ ║
║ │ Image: tesseract.js (OCR) │ ║
║ │ TXT/MD: direct read │ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ Raw text blocks ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 2: PARSE 🔵 Core │ ║
║ │ ┌───────────────┐ ┌───────────────┐ ┌────────────────────┐│ ║
║ │ │ Layout Detect │→│ Section Split │→│ Structure Tagging ││ ║
║ │ │ (layoutDet.) │ │ (sectionSplit.)│ │ (structureTagger) ││ ║
║ │ └───────────────┘ └───────────────┘ └────────────────────┘│ ║
║ │ Outputs: title, sections, components, tags, suggested modes │ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ Parsed structure ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 3: CANONICALIZE ⚫ Sovgn │ ║
║ │ ┌───────────────────────────────────────────────────────────┐│ ║
║ │ │ • Deterministic normalization (volatile fields stripped) ││ ║
║ │ │ • Whitespace collapse · Unicode normalization ││ ║
║ │ │ • Produces identical hash regardless of processing time ││ ║
║ │ └───────────────────────────────────────────────────────────┘│ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ Canonical form ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 4: TRANSFORM 🔵 Core │ ║
║ │ ┌────────────┐ ┌──────────────┐ ┌───────────────┐ │ ║
║ │ │ Governance │ │ Compliance │ │ Brand Style │ │ ║
║ │ │ DAO rules │ │ Reg. checks │ │ FTH theme │ │ ║
║ │ │ Tier ctrl │ │ Jurisdictn │ │ Nav/Gold │ │ ║
║ │ └────────────┘ └──────────────┘ └───────────────┘ │ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ Transformed document ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 5: EXPORT 🔵 Core │ ║
║ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ ║
║ │ │ JSON │ │ HTML │ │ PDF │ │ MD │ │ XML │ │ ║
║ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ Exported files ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 6: FINGERPRINT + SIGN ⚫ Sovgn │ ║
║ │ ┌─────────────────┐ ┌─────────────────┐ │ ║
║ │ │ SHA-256 Hash │ │ Digital Signing │ │ ║
║ │ │ Merkle Root │ │ ESIGN/UETA │ │ ║
║ │ │ Document CID │ │ Certificate Gen │ │ ║
║ │ └─────────────────┘ └─────────────────┘ │ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ Signed + fingerprinted ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 7: ENCRYPT + ANCHOR ⚫ Sovgn │ ║
║ │ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐│ ║
║ │ │ AES-256-GCM │ │ IPFS/Kubo Push │ │ Blockchain ││ ║
║ │ │ PBKDF2 key drv │ │ CID Generation │ │ Timestamp ││ ║
║ │ │ Encrypt at rest │ │ Pin to node │ │ Ledger anchor││ ║
║ │ └─────────────────┘ └─────────────────┘ └───────────────┘│ ║
║ └─────────────────────────────┬──────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────▼──────────────────────────────────┐ ║
║ │ STEP 8: DISTRIBUTE 🟡 Gate │ ║
║ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ ║
║ │ │Email │ │ SMS │ │WhApp │ │Telgm │ │ QR │ │ ║
║ │ │SMTP │ │Telnyx│ │ Meta │ │ Bot │ │ Code │ │ ║
║ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ ║
║ └────────────────────────────────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
→ Detailed Pipeline Documentation
╔═══════════════════════════════════════════════════════════════╗
║ MULTI-PARTY SIGNING CEREMONY ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ 1. SESSION CREATION ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ Operator │───→│ Create │───→│ Assign │ ║
║ │ initiates │ │ Session │ │ Signers │ ║
║ └──────────────┘ └──────────────┘ └──────┬───────┘ ║
║ │ ║
║ 2. DISTRIBUTION │ ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐ ║
║ │ Email link │◀───│ Distribution │◀───│ Generate │ ║
║ │ SMS link │ │ Engine │ │ signing URLs │ ║
║ │ QR code │ │ (nodemailer) │ │ │ ║
║ └──────────────┘ └──────────────┘ └──────────────┘ ║
║ ║
║ 3. SIGNING CEREMONY ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ Signer │───→│ OTP │───→│ Intent │ ║
║ │ clicks link │ │ Verification │ │ Capture │ ║
║ └──────────────┘ └──────────────┘ └──────┬───────┘ ║
║ │ ║
║ 4. COMPLETION │ ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐ ║
║ │ Certificate │◀───│ Fingerprint │◀───│ Apply │ ║
║ │ generated │ │ updated │ │ Signature │ ║
║ └──────────────┘ └──────────────┘ └──────────────┘ ║
║ ║
║ Session States: ║
║ [created] → [distributed] → [signing] → [completed] ║
║ → [expired] ║
╚═══════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════╗
║ SDC — SECURE DOCUMENT CONTROL ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ INTAKE ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ Document │───→│ Intake │───→│ Fingerprint │ ║
║ │ submitted │ │ Engine │ │ + Classify │ ║
║ └──────────────┘ └──────────────┘ └──────┬───────┘ ║
║ │ ║
║ ACCESS CONTROL │ ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐ ║
║ │ OTP verified │───→│ Access Token │───→│ Export │ ║
║ │ identity │ │ generated │ │ Policy check │ ║
║ └──────────────┘ └──────────────┘ └──────┬───────┘ ║
║ │ ║
║ VIEWING │ ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐ ║
║ │ Forensic │───→│ Watermarked │───→│ Secure │ ║
║ │ watermark │ │ render │ │ Viewer │ ║
║ │ applied │ │ │ │ (Port 3003) │ ║
║ └──────────────┘ └──────────────┘ └──────┬───────┘ ║
║ │ ║
║ AUDIT │ ║
║ ┌──────────────────────────────────────────────▼───────┐ ║
║ │ Access Ledger — every view logged with: │ ║
║ │ timestamp · viewer ID · IP · action · hash chain │ ║
║ └──────────────────────────────────────────────────────┘ ║
╚═══════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════╗
║ SCA — SOVEREIGN COMMS AGENT (AI Layer) ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ 📱 Incoming SMS/Voice ║
║ │ ║
║ ┌────▼─────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ Inbound │───→│ Telecom │───→│ AI Intent │ ║
║ │ Router │ │ Registry │ │ Engine │ ║
║ │ (webhook) │ │ (caller ID) │ │ (NLP) │ ║
║ └──────────────┘ └──────────────┘ └──────┬───────┘ ║
║ │ ║
║ Intent Classification: │ ║
║ ┌─────────────────────────────────────────────────┐ ║
║ │ STATUS_QUERY · FUND_REQUEST · DOC_REQUEST · │ ║
║ │ SIGN_REQUEST · ONBOARD · VERIFY · HELP · OTHER │ ║
║ └─────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐ ║
║ │ Response │◀───│ Governance │◀───│ Action │ ║
║ │ Composer │ │ Tier Check │ │ Engine │ ║
║ │ (AI text) │ │ (T0/T1/T2) │ │ (execute) │ ║
║ └──────┬───────┘ └──────────────┘ └──────────────┘ ║
║ │ ║
║ ┌──────▼───────┐ ┌──────────────┐ ║
║ │ Reply via │───→│ Conversation │ ║
║ │ Telnyx SMS │ │ Ledger │ ║
║ └──────────────┘ │ (hash-chain) │ ║
║ └──────────────┘ ║
╚═══════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════╗
║ CLOUDFLARE PERIMETER DEFENSE ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ 🌐 External Request ║
║ │ ║
║ ┌────▼─────────┐ ║
║ │ Cloudflare │ Rules enforced: ║
║ │ Edge │ • WAF (OWASP Top 10) ║
║ │ │ • DDoS mitigation ║
║ │ │ • Bot management ║
║ └──────┬───────┘ • Geo-restriction (optional) ║
║ │ ║
║ ┌──────▼───────┐ ║
║ │ Zero Trust │ Policies: ║
║ │ Access │ • Email identity verification ║
║ │ │ • Device posture checks ║
║ │ │ • Session duration limits ║
║ └──────┬───────┘ ║
║ │ ║
║ ┌──────▼───────┐ ║
║ │ Cloudflare │ Configuration: ║
║ │ Tunnel │ • No exposed ports ║
║ │ (cloudflared)│ • Encrypted channel ║
║ │ │ • Auto-reconnect ║
║ └──────┬───────┘ ║
║ │ ║
║ ┌──────▼───────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ Rate Limiter │───→│ Webhook │───→│ Application │ ║
║ │ (sliding win)│ │ Validator │ │ Services │ ║
║ │ 100/15m/IP │ │ (HMAC sig) │ │ (3001-3005) │ ║
║ └──────────────┘ └──────────────┘ └──────────────┘ ║
║ │ ║
║ ┌──────▼───────┐ ║
║ │ Perimeter │ ║
║ │ Ledger │ ║
║ │ (audit log) │ ║
║ └──────────────┘ ║
╚═══════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════╗
║ HASH-CHAINED LEDGER SYSTEMS ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ Every ledger entry is hash-chained: ║
║ entry.hash = SHA-256(entry.data + previousEntry.hash) ║
║ ║
║ ┌──────────────────┐ ┌──────────────────┐ ║
║ │ 📋 Event Log │ │ 📋 Access Ledger │ ║
║ │ Global system │ │ Document views │ ║
║ │ events │ │ per-recipient │ ║
║ │ Tamper-evident │ │ forensic trace │ ║
║ └──────────────────┘ └──────────────────┘ ║
║ ║
║ ┌──────────────────┐ ┌──────────────────┐ ║
║ │ 📋 Conversation │ │ 📋 Perimeter │ ║
║ │ Ledger │ │ Ledger │ ║
║ │ SMS/Voice logs │ │ Security events │ ║
║ │ AI intent chain │ │ Block/allow log │ ║
║ └──────────────────┘ └──────────────────┘ ║
║ ║
║ ┌──────────────────┐ ┌──────────────────┐ ║
║ │ 📋 Backup │ │ 🗄️ Lifecycle │ ║
║ │ Ledger │ │ Registry │ ║
║ │ Backup events │ │ Version history │ ║
║ │ Encryption log │ │ State machine │ ║
║ └──────────────────┘ └──────────────────┘ ║
║ ║
║ DISTRIBUTED STORAGE ║
║ ┌──────────────────────────────────────────────────────┐ ║
║ │ 🌐 IPFS/Kubo Node (Port 8081) │ ║
║ │ │ ║
║ │ • CID Registry tracks all pinned documents │ ║
║ │ • Content-addressed (immutable by design) │ ║
║ │ • Private swarm key isolation │ ║
║ │ • Automatic garbage collection with pin protection │ ║
║ └──────────────────────────────────────────────────────┘ ║
╚═══════════════════════════════════════════════════════════════╝
| Layer | Controls | Modules |
|---|---|---|
| 🟠 Network | Zero exposed ports · Cloudflare WAF · DDoS mitigation · Rate limiting | perimeter/ (5 files) |
| 🟠 Identity | Zero Trust Access · Email verification · Device posture | perimeter/cloudflareConfig.ts |
| 🟡 Authentication | OTP challenges · Time-limited tokens · Session isolation | gateway/otpEngine.ts · sdc/accessTokenService.ts |
| 🟣 Authorization | Export policies · Tier-based governance · Role enforcement | sdc/exportPolicyEngine.ts · governance/ |
| 🔵 Data | AES-256-GCM encryption · PBKDF2 key derivation · Forensic watermarks | sovereign/ · sdc/watermarkEngine.ts |
| ⚫ Integrity | SHA-256 fingerprints · Merkle trees · Hash-chained ledgers | sovereign/documentFingerprint.ts · all ledgers |
| ⚫ Immutability | IPFS/CID anchoring · Blockchain timestamps · Version registry | ipfs/ · registry/ · sovereign/ledgerAnchor.ts |
| ⚙️ Recovery | Encrypted backups · 15-min intervals · 30-day retention | sovereign/backupAgent.ts |
| Standard | Usage | Configuration |
|---|---|---|
| AES-256-GCM | Document encryption at rest | PBKDF2 (100K iterations, SHA-512) |
| SHA-256 | Fingerprinting, hash chains | Canonical form input |
| HMAC-SHA256 | Webhook signature verification | Per-provider secret keys |
| ESIGN/UETA | Digital signatures | Legally binding under US federal + state law |
╔═══════════════════════════════════════════════════════════════╗
║ GOVERNANCE TIER STRUCTURE ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ ┌────────────────────────────────────────────────────────┐ ║
║ │ TIER 0 — AUTOMATIC 🟢 Auto │ ║
║ │ │ ║
║ │ • Status queries (--help, --audit-trail) │ ║
║ │ • Read-only inspection (--sdc-ledger, --session-status)│ ║
║ │ • Health checks (dashboard, tunnel status) │ ║
║ │ • Determinism verification (test suite) │ ║
║ │ │ ║
║ │ Approval: None · Logged automatically │ ║
║ └────────────────────────────────────────────────────────┘ ║
║ ║
║ ┌────────────────────────────────────────────────────────┐ ║
║ │ TIER 1 — OTP VERIFIED 🟡 OTP │ ║
║ │ │ ║
║ │ • Document viewing (SDC secure viewer) │ ║
║ │ • Signature initiation (signing session creation) │ ║
║ │ • Document downloads (export policy controlled) │ ║
║ │ • Session creation (multi-sig ceremony start) │ ║
║ │ │ ║
║ │ Approval: OTP challenge → Verify → Token → Log │ ║
║ └────────────────────────────────────────────────────────┘ ║
║ ║
║ ┌────────────────────────────────────────────────────────┐ ║
║ │ TIER 2 — MANUAL OPERATOR 🔴 Human │ ║
║ │ │ ║
║ │ • Fund operations (FUND BOND01) │ ║
║ │ • Investor onboarding (new allocator provisioning) │ ║
║ │ • Vault role assignment (permission escalation) │ ║
║ │ • Settlement release (final instruction delivery) │ ║
║ │ │ ║
║ │ Approval: Queue → Dashboard review → Approve/Reject │ ║
║ │ + Operator signature + Governance ledger │ ║
║ └────────────────────────────────────────────────────────┘ ║
╚═══════════════════════════════════════════════════════════════╝
→ Full Governance Documentation
| Port | Service | Layer | Description |
|---|---|---|---|
| 3001 | Web Portal | 🔵 Core | Sovereign web interface |
| 3002 | Signing Gateway | 🟡 Gateway | Multi-party signing ceremonies |
| 3003 | SDC Viewer | 🟣 SDC | Secure document viewer |
| 3004 | SCA Webhooks | 🔴 SCA | Telnyx SMS/Voice inbound |
| 3005 | Monitor Dashboard | ⚙️ Ops | Health monitoring + metrics |
| 5001 | IPFS API | ⚫ Storage | Kubo node API |
| 8081 | IPFS Gateway | ⚫ Storage | Kubo HTTP gateway |
| Service | Base Image | Purpose |
|---|---|---|
fth-engine |
node:20-alpine |
Main application + all layers |
ipfs-kubo |
ipfs/kubo:latest |
Distributed storage node |
cloudflared |
cloudflare/cloudflared |
Zero-trust tunnel |
fth-backup |
node:20-alpine |
Encrypted backup agent |
| Subsystem | Health Check | Metric |
|---|---|---|
| 🔵 Document Engine | Parse test | Documents processed |
| 🟡 Signing Gateway | Session status | Active sessions |
| 🟣 SDC Viewer | Token validation | Viewer accesses |
| 🔴 SCA Layer | Webhook test | Messages processed |
| 🟠 Perimeter | Tunnel status | Blocked requests |
| ⚫ IPFS Node | API ping | Pinned objects |
| ⚫ Ledger Systems | Chain integrity | Ledger entries |
| ⚙️ Backup Agent | Last backup time | Backup size |
| ⚙️ Docker Services | Container status | Uptime |
| Parameter | Default | Description |
|---|---|---|
| Interval | 15 minutes | Backup frequency |
| Encryption | AES-256-GCM | Backup encryption standard |
| Retention | 30 days | Automatic cleanup after retention period |
| Scope | .doc-engine/ |
All ledgers, sessions, tokens, outbox |
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | 20+ | Runtime |
| Docker Engine | 24+ | Container orchestration |
| Docker Compose | v2 | Multi-service deployment |
| Cloudflare Account | — | Zero Trust + Tunnel |
| Telnyx Account | — | SMS/Voice telecom |
git clone https://github.com/FTHTrading/Doc-Intelligence.git
cd Doc-Intelligence
cp .env.example .env # Configure credentials
docker-compose up -d # Start all services| Layer | Directory | Files | Extensions |
|---|---|---|---|
| 🔵 Core Engine | ingest/ parser/ transform/ export/ schema/ |
21 | .ts |
| 🔵 Signature | signature/ |
4 | .ts |
| 🔵 Research | research/ |
7 | .ts |
| 🟡 Signing Gateway | gateway/ |
4 | .ts |
| 🟣 SDC | sdc/ |
7 | .ts |
| 🔴 Telecom/SCA | telecom/ |
6 | .ts |
| 🟠 Perimeter | perimeter/ |
5 | .ts |
| ⚫ Sovereign | sovereign/ |
10 | .ts |
| ⚫ Registry | registry/ |
3 | .ts |
| ⚫ IPFS | ipfs/ |
1 | .ts |
| 🟢 Governance | governance/ |
3 | .ts |
| 🟢 Agreements | agreements/ |
2 | .ts |
| ⚙️ Operations | batch/ web/ styles/ archive/ |
5 | .ts .css |
| ⚙️ Docker | Root | 3 | Dockerfile docker-compose.yml .dockerignore |
| 📄 Documentation | docs/ diagrams/ pages/ pilot/ assets/ |
27 | .md .html .css .svg .json |
| 🧪 Tests | test/ |
2 | .ts |
| ⚙️ Config | Root | 8 | .json .md .yml .gitignore |
| TOTAL | ~130 |
╔═══════════════════════════════════════════════════════════════╗
║ RUNTIME DEPENDENCIES ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ DOCUMENT PROCESSING ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ pdf-parse │ │ mammoth │ │ cheerio │ ║
║ │ PDF → text │ │ DOCX → HTML │ │ HTML parse │ ║
║ └──────────────┘ └──────────────┘ └──────────────┘ ║
║ ║
║ IMAGE & RENDER ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ tesseract.js │ │ puppeteer │ │ sharp │ ║
║ │ OCR engine │ │ PDF render │ │ Image proc │ ║
║ └──────────────┘ └──────────────┘ └──────────────┘ ║
║ ║
║ CRYPTO & COMMS ║
║ ┌──────────────┐ ┌──────────────┐ ║
║ │ crypto-js │ │ nodemailer │ ║
║ │ AES-256-GCM │ │ SMTP email │ ║
║ └──────────────┘ └──────────────┘ ║
║ ║
║ DEV DEPENDENCIES ║
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
║ │ typescript │ │ ts-node │ │ @types/* │ ║
║ │ ^5.9.3 │ │ ^10.9.2 │ │ node,crypto │ ║
║ └──────────────┘ └──────────────┘ └──────────────┘ ║
╚═══════════════════════════════════════════════════════════════╝
These properties hold at all times regardless of system state. They are enforced by architecture, not configuration.
| # | Invariant | Enforcement |
|---|---|---|
| 1 | All documents are hash-addressable | SHA-256 fingerprint computed on every ingest; stored in CID registry |
| 2 | No unsigned document crosses any trust boundary | Gateway rejects documents without valid signature state |
| 3 | All exports are traceable to source | Export metadata embeds source fingerprint + ingest timestamp |
| 4 | No governance decision bypasses tier rules | Governance overlay applied in transform; enforced at gateway + SDC + SCA |
| 5 | No ledger entry can be mutated after write | Append-only stores; each entry hashes predecessor (chain integrity) |
| 6 | Every access event is recorded before access is granted | SDC writes to access ledger before issuing viewer token |
| 7 | No document leaves SDC without watermark | Watermark engine is mandatory in secure viewer pipeline |
| 8 | All perimeter traffic is authenticated before reaching application | Cloudflare Zero Trust + Argo Tunnel; no public IP exposure |
| 9 | OTP codes are single-use and time-bound | CSPRNG generation; 10-minute TTL; 3-attempt maximum; then lockout |
| 10 | System fails closed on any validation error | All validators return deny-by-default; explicit allow required |
Why this matters: Invariants are mathematical properties of the system. They cannot be violated by configuration errors, operator mistakes, or partial deployments. Institutions evaluate infrastructure by its guarantees, not its features.
Summary of attack surfaces, blast radius containment, and recovery pathways.
For the complete threat model, see security/threat-model.md.
| Surface | Entry Point | Defended By |
|---|---|---|
| Network | Public internet → Cloudflare Edge | WAF, DDoS protection, geo-blocking, Zero Trust |
| Application | API endpoints (Ports 3002–3004) | Rate limiting, webhook validation, input sanitization |
| Identity | Signing ceremony, SCA messages | OTP verification, session tokens, registered identities |
| Document | Uploaded files via ingest | Format validation, size limits, MIME type enforcement |
| Supply Chain | npm dependencies | Lockfile pinning, minimal dependency surface |
| Insider | Authorized users exceeding role | Governance tiers, separation of duties, audit trail |
┌────────────────────────────────────────────────────────────────┐
│ MODULE ISOLATION — Failure does not propagate across layers │
├────────────────────────────────────────────────────────────────┤
│ │
│ If PERIMETER fails: │
│ └─ Cloudflare blocks all traffic. No requests reach app. │
│ Recovery: Tunnel reconnect (automatic, <60s) │
│ │
│ If GATEWAY fails: │
│ └─ Signing sessions freeze. No new signatures issued. │
│ Documents remain in last valid state. SDC unaffected. │
│ Recovery: Gateway restart. Sessions preserved on disk. │
│ │
│ If SDC fails: │
│ └─ Viewer unavailable. No document access. No data exposed. │
│ Signed documents remain intact in storage. │
│ Recovery: SDC restart. Tokens re-validated from ledger. │
│ │
│ If SCA fails: │
│ └─ Inbound messages queue at Telnyx. No actions executed. │
│ Gateway + SDC continue independently. │
│ Recovery: SCA restart. Message replay from Telnyx queue. │
│ │
│ If IPFS/Kubo fails: │
│ └─ New anchoring paused. Existing CIDs remain valid. │
│ Local CID registry preserves all references. │
│ Recovery: Kubo restart. Re-pin from local registry. │
│ │
│ If LEDGER fails: │
│ └─ Event logging paused. All modules continue operating. │
│ Events buffered in memory. Flushed on recovery. │
│ Recovery: Restart. Chain integrity verified on resume. │
│ │
└────────────────────────────────────────────────────────────────┘
Design principle: Every module failure is isolated and recoverable. No single component failure causes data loss, unauthorized access, or integrity compromise.
| Resource | Link |
|---|---|
| Source Code | FTHTrading/Doc-Intelligence |
| Documentation | FTHTrading/DOCS (this repo) |
| GitHub Pages | fthtrading.github.io/Doc-Intelligence |
| Security Contact | security@fthtrading.com |
| License | MIT |
| Visual Architecture | Architecture Diagram |
| Threat Model | security/threat-model.md |
◆ From The Hart · Sovereign Document Infrastructure
Built for institutions that require deterministic, auditable, legally binding document operations.
Document integrity is capital integrity. Signing discipline is legal defensibility. Controlled viewing is information asymmetry control. Governance tiers are fiduciary alignment.