# MT Ink Dashboard - PROJECT STATUS
**Last Updated:** February 3, 2026 03:33 CET  
**Current Version:** VERSION 2 — Dynamic Quarterly Projections  
**Status:** 🟢 Production (Stable - 18 days uptime)  
**URL:** https://dashboard.mt.ink  

---

## Quick Status Summary

### System Health
- **Service:** ✅ Running since Jan 16, 2026 10:12 UTC (18+ days)
- **Memory:** 54.6MB (healthy)
- **Database:** ✅ Connected and healthy
- **WebSocket:** ✅ Active (real-time updates working)
- **Response Time:** Fast (HTTP 200 OK)
- **Last Deployed:** January 16, 2026 at 10:07 AM

### Version History
- **Jan 16, 2026:** VERSION 2 deployed (current)
- **Dec 18, 2025:** Major update (backup created)
- **Nov 1, 2025:** Q4 actual data integration
- **Oct 21, 2025:** Q4 projection feature added

---

## Current Dashboard Features (VERSION 2)

### 1. ✅ Today vs Yesterday Comparison
**Status:** LIVE  
**Location:** Top hero card  
**Features:**
- Real-time comparison updating throughout the day
- Shows current time (e.g., "as of 14:30")
- Compares today's sales vs yesterday at same time
- Order count and revenue side-by-side
- Percentage change indicators (green/red)
- Includes "Yesterday's Full Day" card showing complete previous day totals

**API Endpoint:** `/api/comparison/today-vs-yesterday`

### 2. ✅ Average Order Value (AOV) Analysis
**Status:** LIVE  
**Location:** Dedicated AOV section + highlighted metric card  
**Features:**
- Three comparison periods:
  - Today vs Yesterday
  - This Week vs Last Week
  - This Month vs Last Month
- Real-time AOV calculation (Revenue ÷ Orders)
- Percentage change tracking
- Highlighted in metrics grid with 💰 icon
- Color-coded (green for increase, red for decrease)

**Calculation:** Dynamically computed from order count and revenue data

### 3. ✅ Time-Based Comparisons
**Status:** LIVE  
**Location:** Dedicated comparison card  
**Features:**
- **This Week vs Last Week** (same point in week)
- **This Month vs Last Month** (same point in month)
- Shows order progression (e.g., "15 → 23 orders")
- Revenue change with percentage

**API Endpoints:**
- `/api/comparison/week-vs-lastweek`
- `/api/comparison/month-vs-lastmonth`

### 4. ✅ Spotify Pool Payment Analysis
**Status:** LIVE  
**Location:** Dedicated Spotify section  
**Features:**
- **Historical Quarters:** Q1, Q2, Q3, Q4 2025 actual data
  - Q1 2025: $4,822 (812.8 completes, 429,977 mins)
  - Q2 2025: $8,317 (1,045.6 completes, 553,075 mins)
  - Q3 2025: $14,354 (1,707,582 mins, $0.00841/min)
  - Q4 2025: $9,249 (894,829 mins) ✓ ACTUAL
- **Current Pool Rate:** $0.00841/min ($8.41 per 1,000 minutes)
- **Dynamic Q4+ Projections:** Live calculations based on actual data
- **Rate History:** Tracks per-minute payout rates across quarters

**API Endpoint:** `/api/spotify/quarterly-projection`

### 5. ✅ Spotify Listening Analytics
**Status:** LIVE  
**Features:**
- **Last 12 Weeks:** Weekly minutes streamed
- **Estimated Revenue:** Calculated using current pool rate
- **Estimated Completes:** Minutes ÷ 530 (average audiobook length)
- **Country Breakdown:** Last 8 weeks by country with trend indicators
  - Color-coded growth/decline week-over-week
  - Totals per country and per week

**API Endpoints:**
- `/api/spotify/minutes?weeks=12`
- `/api/spotify/countries`

### 6. ✅ Real-Time Order Notifications
**Status:** LIVE  
**Features:**
- WebSocket connection to `wss://dashboard.mt.ink/ws`
- Live order notifications appear in top-right corner
- Shows: Order amount, country (if available)
- Auto-dismisses after 5 seconds
- Dashboard auto-refreshes data on new order
- Reconnects automatically if disconnected

**Technology:** WebSocket (native browser API)

### 7. ✅ Spotify Data Upload Portal
**Status:** LIVE (embedded in dashboard)  
**Location:** Bottom of dashboard  
**Features:**
- Upload CSV/XLSX files directly from dashboard
- Three report types:
  - Monthly Stats (CSV)
  - Weekly Stats (CSV)
  - Revenue Report (XLSX)
- Multi-file upload support
- Progress indicators during upload
- Success/error feedback with detailed messages

**API Endpoint:** POST `/api/upload`

### 8. ✅ Comprehensive Metrics Grid
**Status:** LIVE  
**Features:**
- **Weekly Sales:** Current week revenue + % change
- **Monthly Sales:** Current month revenue + % change
- **This Week Orders:** Order count + % change
- **Average Order Value:** Highlighted card with % change
- **Total Revenue:** 30-day rolling total
- **Yesterday's Total Sales:** Complete previous day (highlighted card)

All cards show:
- Green arrow (↑) for growth
- Red arrow (↓) for decline
- Actual percentage changes

### 9. ✅ Top Countries Analysis
**Status:** LIVE  
**Location:** Countries table  
**Features:**
- Top 10 countries by order count (last 30 days)
- Revenue per country
- Sortable data

**API Endpoint:** `/api/countries`

### 10. ✅ AOV Trend Table
**Status:** LIVE  
**Location:** Dedicated trend section  
**Features:**
- Daily AOV for last 30 days
- Date, Orders, Revenue, AOV columns
- Daily % change tracking
- Color-coded changes (green/red)

**API Endpoint:** `/api/growth/daily?days=30`

### 11. ✅ Revenue by Platform
**Status:** LIVE  
**Location:** Platform table  
**Features:**
- Shopify, Etsy, WooCommerce active platforms
- Order counts and revenue (last 30 days)
- Status indicators (Active/Coming Soon)
- Placeholders for Amazon and eBay

**API Endpoint:** `/api/revenue/platforms`

---

## Technical Architecture

### Frontend
- **Framework:** Vanilla JavaScript (ES6)
- **Styling:** Inline CSS (dark indigo gradient theme)
- **Libraries:**
  - None (pure vanilla JS)
- **Features:**
  - WebSocket for real-time updates
  - Auto-refresh every 60 seconds
  - Responsive design (mobile/tablet/desktop)
  - Touch-friendly for mobile
  - File upload with progress indicators

### Backend
- **Runtime:** Node.js 20
- **Framework:** Express.js (ES6 modules)
- **Port:** 3003 (internal)
- **Database:** PostgreSQL 14 (Digital Ocean managed)
- **WebSocket:** Native ws library
- **CORS:** Enabled for cross-origin requests

### Infrastructure
- **Server:** 143.110.165.195 (Digital Ocean Ubuntu 24.04 LTS)
- **Proxy:** Nginx (HTTPS with Let's Encrypt)
- **Process Manager:** systemd
- **Service:** mt-ink-dashboard.service

### Key Files
```
Production:  /opt/mt-ink-dashboard/
├── server.js              # Express API + WebSocket
├── package.json           # Dependencies
└── public/
    └── index.html        # VERSION 2 dashboard (54KB)

Sandbox:     /opt/mt-ink-dashboard-sandbox/
└── [Same structure for testing]

Docs:        /opt/mt-ink-docs/
├── DASHBOARD-TECH-BIBLE.md
└── MT-INK-TECHNICAL-DOCUMENTATION.md
```

---

## API Endpoints (Complete List)

### Comparison Endpoints
```
GET /api/comparison/today-vs-yesterday
GET /api/comparison/week-vs-lastweek
GET /api/comparison/month-vs-lastmonth
```

### Growth & Metrics
```
GET /api/growth/weekly
GET /api/growth/monthly
GET /api/growth/daily?days=30
```

### Spotify Data
```
GET /api/spotify/minutes?weeks=12
GET /api/spotify/countries
GET /api/spotify/quarterly-projection
```

### Revenue & Platforms
```
GET /api/revenue/platforms
GET /api/countries
```

### Data Upload
```
POST /api/upload
```

### WebSocket
```
wss://dashboard.mt.ink/ws
```

---

## Database Schema (Active Tables)

### Tables in Use
1. **shopify_orders** - Shopify order data
2. **weekly_revenue** - Spotify weekly estimates
3. **monthly_revenue** - Spotify monthly actuals (authoritative)
4. **spotify_weekly_stats** - Detailed Spotify listening data
5. **spotify_country_stats** - Country-level Spotify data

### Sample Queries
```sql
-- Check recent orders
SELECT COUNT(*), SUM(total::decimal) 
FROM shopify_orders 
WHERE created_at >= CURRENT_DATE;

-- Check Spotify data
SELECT * FROM monthly_revenue 
ORDER BY month DESC LIMIT 12;

-- Country breakdown
SELECT country, SUM(minutes) 
FROM spotify_country_stats 
WHERE report_week_start >= CURRENT_DATE - INTERVAL '8 weeks'
GROUP BY country;
```

---

## Deployment History

### January 16, 2026 (CURRENT)
- **What:** VERSION 2 deployed to production
- **Size:** 54KB
- **Backup:** index.html.backup-20251218-150827
- **Status:** Stable, no issues

### December 18, 2025
- **What:** Major feature update
- **Backup:** Created before deploy

### November 1, 2025
- **What:** Q4 actual data integration
- **Backup:** index.html.backup-q4-actual-20251101-105921

### October 21, 2025
- **What:** Q4 projection feature added
- **Backup:** index.html.backup-q4-projection-20251021-092233

---

## Known Issues & Limitations

### Current Issues
- ✅ None - System stable

### Planned Improvements
- [ ] Add Amazon sales integration
- [ ] Add eBay sales integration
- [ ] Create PROJECT-STATUS.md (THIS FILE)
- [ ] Update DASHBOARD-TECH-BIBLE.md with VERSION 2 features
- [ ] Add historical data export feature
- [ ] Add custom date range selector
- [ ] Add email alerts for sales milestones

---

## Maintenance Schedule

### Daily
- WebSocket connections auto-manage (reconnect on failure)
- Database health checks every 5 minutes

### Weekly
- Review logs: `journalctl -u mt-ink-dashboard.service -n 100`
- Check disk space
- Monitor response times

### Monthly
- Database backups
- Review and clean old backups
- Update documentation if changes made

---

## Sandbox Development Policy

### CRITICAL RULE: SANDBOX FIRST, ALWAYS

1. **Make changes in:** `/opt/mt-ink-dashboard-sandbox/`
2. **Test thoroughly:** Check console, data loading, responsiveness
3. **Backup production:** `cp index.html index.html.backup-$(date +%Y%m%d-%H%M%S)`
4. **Deploy:** Copy from sandbox to production
5. **Restart:** `systemctl restart mt-ink-dashboard.service`
6. **Verify:** Check logs and test live site

### Never Edit Production Directly
- Production is `/opt/mt-ink-dashboard/` - **READ ONLY**
- All development in `/opt/mt-ink-dashboard-sandbox/`
- Exception: Emergency hotfixes (with immediate backup)

---

## Quick Commands Reference

```bash
# Service Management
systemctl status mt-ink-dashboard.service
systemctl restart mt-ink-dashboard.service
journalctl -u mt-ink-dashboard.service -f

# File Locations
cd /opt/mt-ink-dashboard/              # Production (READ ONLY)
cd /opt/mt-ink-dashboard-sandbox/      # Development (WORK HERE)
cd /opt/mt-ink-docs/                   # Documentation

# Check what's live
head -3 /opt/mt-ink-dashboard/public/index.html | grep -i version
ls -lh /opt/mt-ink-dashboard/public/index.html

# Database
psql "postgresql://doadmin:PASSWORD@db-postgresql-lon1-83676-do-user-18164855-0.l.db.ondigitalocean.com:25060/mt_ink_sales?sslmode=require"

# Test endpoint
curl https://dashboard.mt.ink/api/comparison/today-vs-yesterday | jq

# Check WebSocket
journalctl -u mt-ink-dashboard.service | grep -i "client connected"
```

---

## Recent Changes Log

### Feb 3, 2026
- ✅ Created PROJECT-STATUS.md (this file)
- ✅ Documented all VERSION 2 features
- ✅ Verified system health (18 days uptime)

### Jan 16, 2026
- ✅ Deployed VERSION 2 to production
- ✅ All features stable and working

### Dec 18, 2025
- ✅ Major dashboard update
- ✅ Added new comparison features

### Nov 1, 2025
- ✅ Integrated Q4 2025 actual Spotify data
- ✅ Updated pool rate calculations

---

## Support & Resources

**Dashboard:** https://dashboard.mt.ink  
**Upload Portal:** https://mcp-server.mt.ink  
**Auth:** dev / Givemelotsofdata13

**Server:** 143.110.165.195  
**SSH:** `ssh root@143.110.165.195`

**Related Services:**
- MCP Server: Port 3000 (Spotify data processing)
- Real-time Sales: https://fuck.letsdoit.ai (Port 3001)

**Documentation:**
- This file: `/opt/mt-ink-docs/PROJECT-STATUS.md`
- Tech Bible: `/opt/mt-ink-docs/DASHBOARD-TECH-BIBLE.md`
- MT Ink Docs: `/opt/mt-ink-docs/MT-INK-TECHNICAL-DOCUMENTATION.md`

---

**Last Updated:** February 3, 2026 03:33 CET  
**Next Review:** March 3, 2026  
**Maintained By:** Ian / Claude