apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-04-27 09:46:25 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat: Add initial strategic planning, UX design, and verification artifacts, define a new AI-powered crypto assistant epic, update existing epics, and disable SSL for local database connection.

Browse source
This commit is contained in:
API Test Bot 2026-02-02 17:43:33 +07:00
parent f21e1a5b58
commit f2e38c52a1
17 changed files with 7028 additions and 739 deletions
Download patch file Download diff file Expand all files Collapse all files

317
_bmad-output/planning-artifacts/ux-design-directions.html Normal file
View file

@ -0,0 +1,317 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>SurfSense v2 - Design Directions</title>
<script src="https://cdn.tailwindcss.com"></script>
<script>
tailwind.config = {
darkMode: 'class',
theme: {
extend: {
colors: {
// Shared Core
background: '#0B1221', // Deep Navy/Dark Gray compromise
foreground: '#ffffff',
card: '#111827', // Gray 900
border: '#1f2937', // Gray 800
// Option A: Safe Pro (Muted)
'safe-success': '#10b981', // Emerald 500
'safe-danger': '#ef4444', // Red 500
// Option B: Cyber (Neon)
'cyber-success': '#00ff9d',
'cyber-danger': '#ff003c',
'cyber-bg': '#000000',
// Option C: Hybrid (Traffic Light)
'hybrid-success': '#22c55e', // Green 500
'hybrid-danger': '#f43f5e', // Rose 500
'hybrid-warning': '#f59e0b', // Amber 500
},
fontFamily: {
sans: ['Geist Sans', 'Inter', 'sans-serif'],
mono: ['Geist Mono', 'JetBrains Mono', 'monospace'],
}
}
}
}
</script>
<style>
/* Custom Scrollbar */
::-webkit-scrollbar { width: 6px; height: 6px; }
::-webkit-scrollbar-track { background: transparent; }
::-webkit-scrollbar-thumb { background: #374151; border-radius: 3px; }
/* Glow Effects for Cyber Mode */
.cyber-glow-text { text-shadow: 0 0 10px currentColor; }
.cyber-border { box-shadow: 0 0 5px rgba(0, 255, 157, 0.2); }
</style>
</head>
<body class="bg-gray-900 text-white font-sans overflow-hidden h-screen flex flex-col">
<!-- Control Panel -->
<div class="bg-gray-800 border-b border-gray-700 p-4 flex items-center justify-between z-50">
<h1 class="text-xl font-bold bg-clip-text text-transparent bg-gradient-to-r from-blue-400 to-teal-400">
SurfSense v2 <span class="text-gray-400 text-sm font-normal">Design Directions</span>
</h1>
<div class="flex gap-2 bg-gray-900 p-1 rounded-lg border border-gray-700">
<button onclick="switchMode('A')" id="btn-A" class="px-4 py-2 rounded text-sm font-medium transition-colors hover:bg-gray-700 text-gray-400">
Option A: Safe Pro
</button>
<button onclick="switchMode('B')" id="btn-B" class="px-4 py-2 rounded text-sm font-medium transition-colors hover:bg-gray-700 text-gray-400">
Option B: Cyber Terminal
</button>
<button onclick="switchMode('C')" id="btn-C" class="px-4 py-2 rounded text-sm font-medium bg-blue-600 text-white shadow-lg">
Option C: Hybrid (Rec)
</button>
</div>
<div class="text-sm text-gray-400">
Click options to toggle visuals
</div>
</div>
<!-- Main Container -->
<div id="mockup-container" class="flex-1 flex overflow-hidden bg-[#0B1221] transition-colors duration-500 relative">
<!-- SIDEBAR -->
<div id="sidebar" class="w-64 border-r border-[#1f2937] flex flex-col p-4 gap-2 transition-all duration-300">
<!-- Brand -->
<div class="flex items-center gap-3 mb-6 px-2">
<div class="w-8 h-8 bg-blue-600 rounded-lg flex items-center justify-center font-bold text-lg">S</div>
<span class="font-bold text-lg tracking-tight">SurfSense</span>
</div>
<!-- Nav Items -->
<div class="space-y-1">
<div class="p-2 rounded bg-blue-500/10 text-blue-400 font-medium flex items-center gap-3">
<span>📊</span> Market Intel
</div>
<div class="p-2 rounded hover:bg-white/5 text-gray-400 font-medium flex items-center gap-3 cursor-pointer">
<span>💼</span> Portfolio
</div>
<div class="p-2 rounded hover:bg-white/5 text-gray-400 font-medium flex items-center gap-3 cursor-pointer">
<span>🔔</span> Smart Alerts
</div>
<div class="p-2 rounded hover:bg-white/5 text-gray-400 font-medium flex items-center gap-3 cursor-pointer">
<span>🤖</span> AI Chat
</div>
</div>
<div class="mt-auto p-4 rounded bg-gray-800/50 border border-gray-700/50">
<div class="text-xs text-gray-400 uppercase font-bold mb-2">Extension Status</div>
<div class="flex items-center gap-2 text-sm text-green-400">
<span class="w-2 h-2 rounded-full bg-green-500 animate-pulse"></span>
Active & Syncing
</div>
</div>
</div>
<!-- CONTENT AREA -->
<div class="flex-1 flex flex-col min-w-0">
<!-- Header -->
<div id="header" class="h-16 border-b border-[#1f2937] flex items-center justify-between px-6 bg-[#0B1221]/50 backdrop-blur">
<div class="flex items-center gap-4 text-sm text-gray-400">
<span>Market Intelligence</span>
<span>/</span>
<span class="text-white">Whale Watch</span>
</div>
<div class="flex items-center gap-4">
<input type="text" placeholder="Search tokens (Cmd+K)..." class="bg-gray-900 border border-gray-700 rounded-md px-3 py-1.5 text-sm w-64 focus:outline-none focus:border-blue-500 transition-colors">
<button class="w-8 h-8 rounded-full bg-gray-800 border border-gray-700 flex items-center justify-center">🔔</button>
<div class="w-8 h-8 rounded-full bg-gradient-to-tr from-purple-500 to-blue-500"></div>
</div>
</div>
<!-- Dashboard Content -->
<div class="flex-1 overflow-auto p-6 space-y-6">
<!-- Stats Row -->
<div class="grid grid-cols-4 gap-4">
<div id="card-1" class="p-4 rounded-xl border border-gray-800 bg-[#111827] shadow-sm">
<div class="text-gray-400 text-sm mb-1">Total Signals</div>
<div class="text-2xl font-bold">1,204</div>
<div class="text-green-500 text-xs mt-2 flex items-center gap-1">
<span>↑ 12%</span> <span class="text-gray-500">vs yesterday</span>
</div>
</div>
<div id="card-2" class="p-4 rounded-xl border border-gray-800 bg-[#111827] shadow-sm">
<div class="text-gray-400 text-sm mb-1">High Risk Detected</div>
<div class="text-2xl font-bold text-red-500">23</div>
<div class="text-red-500/80 text-xs mt-2">Critical Awareness</div>
</div>
<div id="card-3" class="p-4 rounded-xl border border-gray-800 bg-[#111827] shadow-sm">
<div class="text-gray-400 text-sm mb-1">Whale Inflow</div>
<div class="text-2xl font-bold text-blue-400">$34.2M</div>
<div class="text-gray-500 text-xs mt-2">Last 24h</div>
</div>
<!-- AI INSIGHT WIDGET -->
<div id="ai-card" class="p-4 rounded-xl border border-blue-900/30 bg-blue-900/10 shadow-sm relative overflow-hidden">
<div class="absolute top-0 left-0 w-1 h-full bg-blue-500"></div>
<div class="flex items-start gap-3">
<span class="text-xl">🤖</span>
<div>
<div class="text-blue-300 font-bold text-sm mb-1">AI Insight</div>
<div class="text-xs text-blue-200/80 leading-relaxed">
"ETH whale accumulation detected in L2 sector. <span class="underline decoration-dotted cursor-pointer hover:text-white">ARB</span> and <span class="underline decoration-dotted cursor-pointer hover:text-white">OP</span> showing divergent strength."
</div>
</div>
</div>
</div>
</div>
<!-- Main Table -->
<div id="main-table" class="rounded-xl border border-gray-800 bg-[#111827] overflow-hidden">
<div class="p-4 border-b border-gray-800 flex justify-between items-center">
<h3 class="font-bold">Live Market Opportunities</h3>
<div class="flex gap-2">
<button class="px-3 py-1 rounded text-xs border border-gray-700 hover:bg-gray-800 transition-colors">Filter</button>
<button class="px-3 py-1 rounded text-xs border border-gray-700 hover:bg-gray-800 transition-colors">Export</button>
</div>
</div>
<table class="w-full text-left text-sm">
<thead class="bg-gray-900/50 text-gray-400 border-b border-gray-800">
<tr>
<th class="p-4 font-medium">Token</th>
<th class="p-4 font-medium">Price</th>
<th class="p-4 font-medium">Risk Score</th>
<th class="p-4 font-medium">Whale Activity</th>
<th class="p-4 font-medium text-right">Action</th>
</tr>
</thead>
<tbody id="table-body" class="divide-y divide-gray-800">
<!-- Rows injected by JS -->
</tbody>
</table>
</div>
</div>
</div>
</div>
<script>
const mockupContainer = document.getElementById('mockup-container');
const sidebar = document.getElementById('sidebar');
const cards = document.querySelectorAll('[id^="card-"]');
const mainTable = document.getElementById('main-table');
const tableBody = document.getElementById('table-body');
const styleConfigs = {
'A': {
name: 'Safe Pro',
classes: {
bg: 'bg-[#0f172a]', // Slate 900
sidebarBorder: 'border-slate-800',
cardBorder: 'border-slate-700',
cardBg: 'bg-slate-800',
text: 'text-slate-200',
tableRow: 'hover:bg-slate-700/50 transition-colors',
},
rowData: [
{ name: 'PEPE', price: '$0.000012', risk: 'Low', riskColor: 'text-emerald-400 bg-emerald-400/10', whale: 'Normal', id: 1 },
{ name: 'TRUMP', price: '$4.32', risk: 'Medium', riskColor: 'text-yellow-400 bg-yellow-400/10', whale: 'High', id: 2 },
{ name: 'SCAM', price: '$0.12', risk: 'Device Scan Failed', riskColor: 'text-red-400 bg-red-400/10', whale: 'Dumping', id: 3 },
]
},
'B': {
name: 'Cyber Terminal',
classes: {
bg: 'bg-black',
sidebarBorder: 'border-green-900/30',
cardBorder: 'border-green-800/50',
cardBg: 'bg-black/80',
text: 'text-green-50 font-mono',
tableRow: 'hover:bg-green-900/20 text-xs font-mono border-green-900/30',
},
rowData: [
{ name: 'PEPE', price: '$0.000012', risk: '[SAFE]', riskColor: 'text-[#00ff9d] drop-shadow-[0_0_5px_rgba(0,255,157,0.5)]', whale: '>> ACCUMULATING', id: 1 },
{ name: 'TRUMP', price: '$4.32', risk: '[WARN]', riskColor: 'text-yellow-400', whale: '>> SPIKE DETECTED', id: 2 },
{ name: 'SCAM', price: '$0.12', risk: '[CRITICAL]', riskColor: 'text-[#ff003c] drop-shadow-[0_0_5px_rgba(255,0,60,0.5)]', whale: '!! DUMPING !!', id: 3 },
]
},
'C': { // Hybrid
name: 'Hybrid',
classes: {
bg: 'bg-[#0B1221]',
sidebarBorder: 'border-gray-800',
cardBorder: 'border-gray-800',
cardBg: 'bg-[#111827]',
text: 'text-white',
tableRow: 'hover:bg-gray-800/50 transition-colors font-sans',
},
rowData: [
{ name: 'PEPE', price: '$0.000012', risk: 'Safe', riskColor: 'text-green-500 font-bold', whale: 'Accumulating', id: 1 },
{ name: 'TRUMP', price: '$4.32', risk: 'Review', riskColor: 'text-amber-500 font-bold', whale: 'High Vol', id: 2 },
{ name: 'SCAM', price: '$0.12', risk: 'Danger', riskColor: 'text-rose-500 font-bold', whale: 'Dump Warning', id: 3 },
]
}
};
function renderRows(configType) {
const config = styleConfigs[configType];
tableBody.innerHTML = config.rowData.map(row => `
<tr class="${config.classes.tableRow}">
<td class="p-4">
<div class="flex items-center gap-3">
<div class="w-8 h-8 rounded-full bg-gray-700 flex items-center justify-center text-xs">IMG</div>
<span class="font-bold">${row.name}</span>
</div>
</td>
<td class="p-4 tabular-nums text-gray-300 font-mono">${row.price}</td>
<td class="p-4">
<span class="px-2 py-1 rounded text-xs ${row.riskColor} border border-current/20">
${row.risk}
</span>
</td>
<td class="p-4 text-gray-400 text-xs">${row.whale}</td>
<td class="p-4 text-right">
<button class="bg-blue-600/20 text-blue-400 hover:bg-blue-600 hover:text-white px-3 py-1 rounded text-xs transition-all border border-blue-500/30">
Analyze
</button>
</td>
</tr>
`).join('');
}
function switchMode(mode) {
// Update Buttons
['A', 'B', 'C'].forEach(m => {
const btn = document.getElementById(`btn-${m}`);
if (m === mode) {
btn.classList.remove('bg-gray-900', 'text-gray-400');
btn.classList.add('bg-blue-600', 'text-white', 'shadow-lg');
} else {
btn.classList.add('bg-gray-900', 'text-gray-400');
btn.classList.remove('bg-blue-600', 'text-white', 'shadow-lg');
}
});
const config = styleConfigs[mode];
// Update Global Containers
mockupContainer.className = `flex-1 flex overflow-hidden ${config.classes.bg} transition-colors duration-500 relative`;
sidebar.className = `w-64 border-r ${config.classes.sidebarBorder} flex flex-col p-4 gap-2 transition-all duration-300`;
// Update Cards
cards.forEach(card => {
card.className = `p-4 rounded-xl border ${config.classes.cardBorder} ${config.classes.cardBg} shadow-sm`;
});
// Update Table Container
mainTable.className = `rounded-xl border ${config.classes.cardBorder} ${config.classes.cardBg} overflow-hidden`;
// Render Table Rows
renderRows(mode);
}
// Init
switchMode('C');
</script>
</body>
</html>

142
_bmad-output/planning-artifacts/ux-design-specification.md Normal file
View file

@ -0,0 +1,142 @@
---
stepsCompleted:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
inputDocuments:
- _bmad-output/planning-artifacts/prd.md
- _bmad-epics/epic-1-ai-powered-crypto-assistant.md
- _bmad-epics/epic-2-smart-monitoring-alerts.md
- _bmad-epics/epic-3-trading-intelligence.md
- _bmad-epics/epic-4-content-creation-productivity.md
---
# UX Design Specification SurfSense
**Author:** Luis
**Date:** 2026-02-02
---
<!-- UX design content will be appended sequentially through collaborative workflow steps -->
## Executive Summary
### Project Vision
SurfSense 2.0 transforms from a general-purpose tool into a **specialized AI Co-pilot for Crypto Traders**. The core value proposition shifts from passive data aggregation to **proactive intelligence**—providing "Smart Monitoring," "Trading Intelligence," and "Content Creation" tools that work seamlessly alongside the trader's workflow.
### Target Users
* **Momentum Traders:** Need real-time, "hot" information (Whale alerts, Volume spikes) to catch rapid price movements. They prioritize speed and accessibility (Extension).
* **Cautious Investors:** Prioritize safety and due diligence. They need tools to verify contracts, detect rug pulls, and analyze long-term metrics.
* **Content Creators:** Use the platform to generate insights and share them (charts, threads) to build their audience.
### Key Design Challenges (Web-First)
* **Data Density vs. Clarity:** The new features (Portfolio, Market Intelligence) introduce complex data (charts, tables, metrics) that must be displayed without overwhelming the user, distinguishing this from the chat-heavy v1.
* **Navigation Scalability:** The current chat-centric sidebar is insufficient for a multi-module application. We must integrate new functional areas (Market, Portfolio, Alerts) without burying them or cluttering the interface.
* **Hybrid Workflow:** Users will constantly switch between "Deep Dive" analysis on the Web Dashboard and "Quick Checks" via the Extension. The experience must be consistent and synchronized.
### Design Opportunities
* **Hybrid Interface Structure:** Transitioning the Web Dashboard from a purely "Chat UI" to a **"Hybrid Interface"** that balances **App Modules** (for data/tools) with the **AI Assistant** (for query/support). This allows distinct spaces for "doing" (Trading/Monitoring) and "asking" (Chat).
* **Unified Design System:** Leveraging the existing Web Design System (Tailwind/Shadcn) to rapidly build the Extension UI, ensuring a consistent look and feel while reducing development effort ($18K constraint).
## Core User Experience
### Defining Experience: "The Intel Layer"
SurfSense is not where users go to *see* price (they use DexScreener for that), but where they go to *see* **The Truth**. The defining interaction is an **"Instant Reality Check"**: while the chart shows hype (FOMO), SurfSense overlays the cold, hard data (Risk/Whale movement), allowing users to verify a trade in seconds. It acts as the "Verify" step in the "Detect → Verify → Act" loop.
### User Mental Model
* **The Old Way:** See price spike → Check Twitter (hype) → Search Contract (manual) → Check Holders → Panic/FOMO → Buy blindly.
* **The SurfSense Way:** See price spike → **Glance at Extension (Traffic Light)**:
* 🔴 **Red:** Ignore immediately (Rug/Honeypot). Time saved: 10 mins.
* 🟢 **Green:** Trade with confidence.
* 🟡 **Yellow:** "Investigate" → One click to open Web Dashboard for deep reasoning (Whale behavior, Fresh wallet movement).
### Platform Strategy
* **Web Dashboard (Master):** The "Command Center" for Portfolio, Alert Management, and Deep Intelligence Analysis. Focuses on **textual/numerical insights** over graphical charts.
* **Extension (Satellite):** The "Tactical" tool for instant context. Smartly advises the user based on their current active tab using the **"Symbiotic Side-Panel"** pattern (lives alongside the chart, doesn't block it).
### Experience Mechanics
1. **Initiation:** User navigates to a token on DexScreener/Twitter.
2. **Interaction:** Extension Badge updates color (Red/Green). User clicks for Summary Overlay.
3. **Cross-Over:** User clicks "Open Dashboard" for deep dive (if needed). Web App opens to the exact token context.
4. **Completion:** User executes trade on DexScreener (or bot) with full confidence.
### Success Criteria
* **Time-to-Truth < 5s:** User determines safety (SCAM vs LEGIT) within 5 seconds of landing on a chart.
* **"Savior" Frequency:** User experiences a "saved me from a rug" moment at least once per week.
* **Zero-Context Switching:** User never manually copies a contract address; the system auto-detects context.
### Novel UX Patterns
* **"Evidence-First" AI:** Insights are always coupled with proof (e.g., "Bullish *because* 3 whales bought" with links to txns), avoiding "Black Box" trust issues.
* **Traffic Light Risk Coding:** Universal color cues (Green=Safe, Yellow=Caution, Red=Danger) for Risk Scores allow scanning in < 1 second.
## Desired Emotional Response
### Primary Emotional Goals
* **Confidence (Tự tin):** Users feel they possess "Insider Intelligence" that others missing by relying solely on charts. The AI provides the "Why" behind the price action.
* **Calm (Bình tĩnh):** In a chaotic market (FOMO, rapid candles), SurfSense acts as a stabilizing anchor, providing "Cold Hard Data" (Risk Scores, On-chain metrics) to rationalize decision-making.
* **Clarity (Sự rõ ràng):** Cutting through the noise of social media and complex charts to show the simple truth about a token's safety and potential.
### Emotional Journey Mapping
* **Trigger (Alert):** **Urgency & Curiosity.** "Whale Accumulating" alert sparks immediate interest but balanced with a need to know *why*.
* **Action (Verify):** **Reassurance.** Opening the dashboard confirms safety (Verified Contract) and validates the trend (AI Sentiment). Confusion turns into clarity.
* **Result (Decision):** **Superiority & Relief.** User feels smarter than the herd ("I avoided a rug pull" or "I caught a trend early").
## UX Pattern Analysis & Inspiration
### Inspiring Products Analysis
* **DexScreener (Crypto):** Excellent **Data Density**. They maximize screen real estate to show price, txns, and liquidity simultaneously without clutter. *Inspiration: High-density layouts using color coding (Green/Red) to direct attention.*
* **GMGN.ai (Crypto):** Strong **Risk Visualization**. They surface hidden risks (dev dumping, high holder concentration) prominently. *Inspiration: "Warning Badges" and "Risk Clusters" that are impossible to ignore.*
* **Perplexity AI (Non-Crypto):** Mastering **Trust & Citations**. Every AI claim is backed by a source link. *Inspiration: SurfSense AI insights should link back to source data (e.g., "Whale bought" -> Link to Txn).*
* **Linear (Productivity):** **Keyboard-First Navigation** and speed. *Inspiration: Power user shortcuts (Cmd+K) for quick search and navigation between modules.*
### Key Takeaways
* **Terminal-Style Efficiency:** Use a dense, tabular view for the "Market Intelligence" module (Web Dashboard) to allow sorting/filtering of 50+ tokens instantly.
* **No Chart, Just Intel:** Don't replicate DexScreener. Provide the "Why" (Insights) behind the "What" (Price).
## Design System Foundation
### 1.1 Design System Choice
**Shadcn/UI + Tailwind CSS** (Confirmed Existing Stack).
### Rationale for Selection
* **Consistency:** The existing `surfsense_web` frontend already utilizes Tailwind CSS (v4) and Shadcn/UI components (Radix primitives). Maintaining this stack ensures zero friction between the current codebase and new v2 features.
* **Inheritance:** The Extension (Slave) will directly inherit color tokens and typography from the Web Dashboard's `tailwind.config.js`, ensuring a unified brand experience with minimal effort.
### Implementation Approach
* **Web-First Truth:** The Web Dashboard remains the "Master" for design tokens and component definitions.
* **Dark Mode Native:** The system is already optimized for Dark Mode, which aligns perfectly with the crypto trading persona.
* **Customization:** Extend default Shadcn theme with "Signal Colors" (Neon Green, Alert Red) for financial data visualization.
## Visual Design Foundation
### Color System
* **Core Palette (Inherited):** Maintain established `globals.css` structure (OKLCH variables) for 100% implementation speed.
* Background: `oklch(0.145 0 0)` (Dark Gray) for enterprise-grade stability.
* Foreground: `oklch(0.985 0 0)` (White).
* **Signal Colors (New):** High-saturation "Neon" variants for "Traffic Light" indicators in Dark Mode.
* 🟢 **Success:** `oklch(0.6 0.18 145)` (Neon Green) - Use for "Safe", "Verified", "Buy Signal".
* 🔴 **Danger:** `oklch(0.6 0.2 25)` (Neon Red) - Use for "Scam", "Rug Risk", "Sell Signal".
* 🟡 **Warning:** `oklch(0.8 0.15 85)` (Amber) - Use for "Caution", "Low Liquidity".
### Typography System
* **Primary Font:** **Geist Sans** (Inherited).
* *Rationale:* Optimized for Vercel/Next.js stack, zero layout shift, and includes excellent **tabular figures** for price data.
* *Usage:* All UI text, headers, and especially data tables.
* **Tone:** Professional, direct, data-first. No decorative serifs.
### Spacing & Layout Foundation
* **Base Unit:** `0.25rem` (4px). Standard Tailwind grid.
* **Radius:** `0.625rem` (Default) for cards/inputs to match existing Web UI.
* **Density Strategy:**
* **Extension:** "Standard" density for touch/click friendliness.
* **Market Intelligence (Web):** "Compact" density to maximize rows per screen (Terminal feel).
### Accessibility Considerations
* **High Contrast Signals:** Prioritize distinctive colors for status indicators (Red/Green) but ensure they are accompanied by text/icon labels (not color-only) to support color-blind users.
* **Dark Mode Optimization:** Ensure text contrast remains high (AA standard) against the dark gray background.