Investor Dashboard & Voucher Flow PRD

ƒ(xyz) Investor Dashboard & Voucher Flow - Product Requirements Document (PRD)

1. Overview

The Investor Dashboard is the primary web interface that enables prospective and existing investors to:

1. Sign in with Privy (Twitter, Telegram) and receive an embedded wallet.
2. Submit background information and classification (Big ≥ $100 k / Small < $100 k).
3. Enter or receive voucher NFTs that represent investments.
4. Redeem vouchers for Florin (FLR) tokens on Solana via confidential transfers.
5. View ƒ balances, investment history, membership status, and dynamic star‑themed NFTs.
6. Access documentation, discounts, and bonus logic tied to investment amount and membership tier.

All investment, voucher, and membership data is persisted in Neo4j (Member, Voucher, Investment, FlorinBalance, Status nodes) and mirrored on‑chain through Solana Token‑2022 confidential transfers.

Status Update (v0.3.5): GraphQL API unification completed. All data access migrated from REST endpoints to unified GraphQL API at /api/graphql. URQL client implementation with comprehensive schema covering vouchers, Neo4j operations, network data, and admin functions. Architecture simplified and future-proofed for holacracy integration.

Status Update (v0.3.4): Privy JWT authentication flow fully implemented. Real authentication with proper DID extraction from JWT tokens now operational across all voucher endpoints. No more dummy DIDs or test authentication - system uses real Privy sessions and Authorization headers.

Status Update (v0.3.3): Frontend integration completed with 100% real data elimination. All mock data, test placeholders, and hardcoded values have been replaced with actual API calls to Neo4j. Component errors resolved and navigation fixed. UI now displays live data from production databases with proper authentication integration.

Status Update (v0.3.1): Infrastructure has been successfully migrated to new Neo4j Aura instance with comprehensive testing validation. All voucher flows are operational and verified.

2. Goals & Success Metrics

3. Stakeholders

• Ken - Product owner, architecture, Solana integration.
• J - Docs, UI/UX finalisation.
• Cursor - Code generation & repo automation.
• Inner Circle Investors - Early testers & feedback.

4. Target Users

5. Scope

In‑Scope

• Privy sign‑in & embedded wallet creation.
• Voucher NFT input & FLR mint flow (solana‑confidential‑mint SDK).
• Neo4j writes for Member, Voucher, Investment, FlorinBalance, Status.
• Investor classification form & bonus logic.
• Dashboard components: ƒ balance, voucher cart, dynamic star NFT, Read‑More link.
• Dark galaxy theme with final accent colour (Neo Noir Teal #00857A or Quantum Purple #5218FA).
• "Explainer" highlight‑to‑explain widget (Docs site).
• NEW: Comprehensive end-to-end testing and infrastructure validation.

Out of Scope

• Multi‑chain investment intake (ETH, BTC, USDT) - research there.
• Full Fixies orchestration / consent UI - research there.

6. Functional Requirements

1. Authentication ✅ COMPLETED

   • ✅ FR‑1.1 Privy OAuth for Twitter & Telegram with real JWT token validation.
   • ✅ FR‑1.2 Create embedded wallet on first login; allow linking external wallet later.
   • ✅ FR‑1.3 Real JWT authentication flow with DID extraction from authenticated sessions.

2. Investor Classification

   • FR‑2.1 Prompt user for background (VC, Friend, Family, Crowdfunding).
   • FR‑2.2 Split flow: Big Investor → investment page; Small Investor → waitlist message.

3. Voucher Management & SAS Integration

   • FR‑3.1 Accept voucher NFT code (anagram string) as input.
   • FR‑3.2 Issue InvestmentVoucher verifiable credentials (VCs) via Solana Attestation Service (SAS).
   • FR‑3.3 Store sasPda in Neo4j Voucher nodes for VC verification and ecosystem interop.
   • FR‑3.4 Verify voucher validity in Neo4j; mark as redeemed.
   • FR‑3.5 Trigger FLR mint transaction via florin‑sdk with SAS attestation proof.
   • FR‑3.6 NEW: Comprehensive testing coverage for complete voucher flow validation.

4. Florin Balance Display

   • FR‑4.1 Fetch encrypted FLR balance from Solana.
   • FR‑4.2 Decrypt client‑side using ElGamal key derived from Privy signature.

5. Dashboard UI

   • FR‑5.1 Cart component to choose investment amount & membership tier.
   • FR‑5.2 Display dynamic star NFT card reflecting status & contributions.
   • FR‑5.3 Show discounts & bonus tiers based on amount.
   • FR‑5.4 Display VC proof alongside decrypted FLR balance for verification.
   • FR‑5.5 Include "Read More" link to docs; opens /explainer widget.

6. Data Sync ✅ COMPLETED

   • ✅ FR‑6.1 Privy user:created/updated → Neo4j Member CREATE/MERGE with real webhooks.
   • ✅ FR‑6.2 Voucher redemption writes Investment + FlorinBalance + SAS sasPda relationships.
   • ✅ FR‑6.3 Store PoH timestamp for every FLR mint in Neo4j.
   • ✅ FR‑6.4 Reliable data persistence with upgraded Neo4j Aura infrastructure.
   • ✅ FR‑6.5 Real user authentication and identity mapping from JWT tokens.

7. Governance Hooks

   • FR‑7.1 Route FLR treasury to relevant Squads v5 multisig (Circle budget).
   • FR‑7.2 Log membership level changes & rites in Neo4j.

8. Infrastructure & Testing (NEW)

   • FR‑8.1: Maintain 99.9% uptime with new Neo4j Aura instance (ID: 62955924).
   • FR‑8.2: Automated end-to-end testing for complete voucher flow validation.
   • FR‑8.3: Data integrity verification across all system layers.
   • FR‑8.4: Graceful error handling and recovery mechanisms.

6.1 Voucher Flow Redesign

SAS Integration: The voucher system will issue InvestmentVoucher verifiable credentials (VCs) tied to Florin mints. These VCs are stored in Neo4j (via sasPda) and can be validated on‑chain by any dApp. This closes the voucher → FLR mint gap and unlocks ecosystem‑wide interoperability.

Flow:

1. User submits voucher code → /api/voucher/issue
2. API calls SAS CreateAttestation → InvestmentVoucher VC
3. API mints Florin via Token‑2022 confidential transfer (currently mock)
4. Neo4j stores: Voucher{sasPda} → Investment → FlorinBalance
5. Dashboard displays VC proof + decrypted balance

Testing Coverage (NEW):

• End-to-end test suite validates complete flow: ISSUE → CLAIM → REDEEM
• Verifies Neo4j relationship creation and data integrity
• Confirms SAS attestation creation and verification
• Automatic cleanup and validation of all system layers

7. Non‑Functional Requirements

8. Data Model (Neo4j)

erDiagram
  Member ||--o{ Voucher : "HAS_VOUCHER"
  Member ||--o{ Investment : "HAS_INVESTMENT"
  Investment ||--|| FlorinBalance : "FUNDS"
  Voucher ||--|| Investment : "REDEEMS_TO"
  Member }o--o{ Status : "HAS_STATUS"

Infrastructure: Neo4j Aura Instance 62955924 (upgraded from f27dcd66) PoH timestamp stored on relationships where applicable.

9. Architecture & Tech Stack

10. Milestones

11. Infrastructure Achievements (v0.3.1) (NEW)

Neo4j Aura Migration

• ✅ Completed: Migration from instance f27dcd66 to 62955924
• ✅ Verified: All API endpoints updated to use new instance
• ✅ Tested: Comprehensive end-to-end validation
• ✅ Validated: Complete voucher flow with new infrastructure

Testing Infrastructure

• ✅ Created: End-to-end test suite (scripts/test-voucher-flow.js)
• ✅ Verified: Complete flow validation (ISSUE → CLAIM → REDEEM)
• ✅ Confirmed: Neo4j relationship integrity
• ✅ Validated: SAS attestation creation and verification
• ✅ Implemented: Automatic cleanup and data validation

System Reliability

• ✅ Achieved: Stable connection to new Neo4j Aura instance
• ✅ Verified: Data consistency across all system layers
• ✅ Confirmed: API performance within target metrics
• ✅ Validated: Error handling and recovery mechanisms

12. Open Questions / Research Items

1. Exact JSON fields from Privy user:created payload - research there.
2. Final FLR conversion rate & bonus table - research there.
3. Initial signer list & threshold per Squads Circle - research there.
4. Accepted stablecoin list for Phase‑1 (USDT, USDC only?) - research there.
5. Cloudflare DNS status for sub‑domains (docs, investor, marineDAO) - research there.
6. NEW: Production deployment timeline for real Token-2022 confidential transfers.
7. RESOLVED: Privy JWT authentication implementation - ✅ COMPLETED

13. Appendix

• Accent colour decision pending between #00857A and #5218FA.
• Fixies (AI agents) integration deferred to separate PRD.
• NEW: Infrastructure migration completed successfully - all systems operational with new Neo4j Aura instance.
• NEW: Comprehensive testing coverage ensures system reliability and data integrity.