navidocs/STACKCP_S2_SWARM_DEPLOYMENT.md

NaviDocs StackCP S2 Swarm Deployment Plan

DEADLINE: 5 hours to working demo STATUS: ✅ READY TO EXECUTE STRATEGY: Maximum velocity via parallel Claude Code CLI agents

---

🎯 Mission

Deploy fully functional NaviDocs on StackCP shared hosting using 5 parallel Claude Code CLI agents working simultaneously, ready for Riviera Plaisance presentation in 5 hours.

---

🏗️ Architecture Overview

StackCP Server (ssh.gb.stackcp.com)
├── /tmp/navidocs/                    # Executable code location
│   ├── server/                       # Backend (Express.js + SQLite)
│   ├── client/                       # Frontend (Vue 3)
│   ├── uploads/                      # Temp file uploads
│   └── .env                          # Configuration
│
├── ~/navidocs-data/                  # Persistent data (noexec OK)
│   ├── db/navidocs.db                # SQLite database
│   ├── uploads/                      # Permanent uploads
│   └── logs/                         # Application logs
│
└── ~/public_html/digital-lab.ca/navidocs/  # Static frontend (served by Apache)

External Services:

• Redis Cloud: Free 30MB tier (job queue)
• Meilisearch: Running on localhost:7700 (already installed)
• Google Vision API: For OCR (handwriting + context understanding)
• Claude Code CLI: For intelligent document analysis

---

🤖 S2 Swarm: 5 Parallel Agents

Agent 1: Backend Developer (S2-BACKEND)

tmux session: backend-dev Working directory: /tmp/navidocs/server Claude session: /tmp/claude → Backend development mode

Tasks (Priority Order):

1. Database Setup (10 min)

   • Deploy schema to ~/navidocs-data/db/navidocs.db
   • Run migrations (warranty_tracking, webhooks, sale_workflows)
   • Seed test data (1 organization, 3 boats, 10 documents)

2. Core API Endpoints (60 min)

   • Auth: /api/auth/register, /api/auth/login (JWT)
   • Documents: /api/documents/upload, /api/documents/list
   • Warranties: /api/warranties/list, /api/warranties/expiring
   • Search: /api/search (Meilisearch integration)

3. Background Worker (30 min)

   • OCR processing queue (BullMQ + Redis Cloud)
   • Warranty expiration checker
   • Document indexing to Meilisearch

4. Testing (15 min)

   • curl test all endpoints
   • Upload 3 test PDFs
   • Verify OCR processing

Handoff to Agent 2: API endpoints ready, database populated

---

Agent 2: Frontend Developer (S2-FRONTEND)

tmux session: frontend-dev Working directory: /tmp/navidocs/client Claude session: /tmp/claude → Frontend development mode

Tasks (Priority Order):

1. Core UI Components (45 min)

   • Login/Register forms (using Session 3 design system)
   • Document upload interface
   • Document list with search
   • Warranty dashboard

2. Navigation & Layout (30 min)

   • Top nav (logo, search, user menu)
   • Sidebar (boats, documents, warranties, settings)
   • Responsive mobile layout

3. Build & Deploy (15 min)

   • npm run build
   • Copy dist/* to ~/public_html/digital-lab.ca/navidocs/
   • Configure API proxy (Apache .htaccess)

4. Testing (15 min)

   • Test login flow
   • Upload document
   • Search functionality
   • Warranty list

Handoff to Agent 3: UI built, deployed, tested

---

Agent 3: OCR Integration Specialist (S2-OCR)

tmux session: ocr-dev Working directory: /tmp/navidocs/server/services Claude session: /tmp/claude → OCR development mode

Tasks (Priority Order):

1. Claude Code CLI OCR (30 min)

   • Create ocr-claude.js using /tmp/claude CLI
   • Extract text + understand context (equipment names, dates, warranty periods)
   • Structured output: { text, equipment: [], warranties: [], dates: [] }

2. Google Vision API Fallback (20 min)

   • Install @google-cloud/vision (in /tmp/navidocs/server)
   • Create ocr-google-vision.js
   • Handle handwriting detection
   • Multi-page PDF processing

3. Hybrid Strategy (20 min)

   • Create ocr-hybrid.js orchestrator
   • Try Claude Code CLI first (faster, understands context)
   • Fallback to Google Vision if Claude fails
   • Log which engine was used

4. Testing (20 min)

   • Test with typed PDF (warranty certificate)
   • Test with handwritten receipt
   • Test with multi-page manual
   • Verify equipment extraction accuracy

Handoff to Agent 4: OCR working for all document types

---

Agent 4: Infrastructure & DevOps (S2-INFRA)

tmux session: infra Working directory: /tmp/navidocs Claude session: /tmp/claude → Infrastructure mode

Tasks (Priority Order):

1. Environment Configuration (15 min)

   • Create /tmp/navidocs/server/.env with all config
   • Redis Cloud connection (get credentials)
   • Google Vision API credentials (copy from user)
   • Meilisearch localhost:7700 connection
   • JWT secrets generation

2. Process Management (20 min)

   • Create systemd-style service scripts (using screen/tmux)
   • Start scripts: navidocs-api, navidocs-worker, navidocs-search
   • Stop/restart scripts
   • Health check script

3. Apache Reverse Proxy (15 min)

   • Configure .htaccess for API proxy
   • /api/* → http://localhost:8001/api/*
   • Static files served from ~/public_html
   • Enable CORS for dev

4. Monitoring & Logging (15 min)

   • Centralized logging to ~/navidocs-data/logs/
   • Error tracking (capture stack traces)
   • Performance monitoring (response times)
   • Disk space alerts

Handoff to Agent 5: Infrastructure ready, services running

---

Agent 5: QA & Integration Testing (S2-QA)

tmux session: qa Working directory: /tmp/navidocs/tests Claude session: /tmp/claude → QA mode

Tasks (Priority Order):

1. End-to-End Test Suite (45 min)

   • User registration → login → JWT token
   • Upload PDF → OCR processing → search
   • Warranty tracking → expiration alerts
   • Multi-boat organization setup
   • Camera integration mock

2. Demo Data Preparation (30 min)

   • Create "Riviera Plaisance" organization
   • 3 boats: Azimut 55S, Princess V50, Sunseeker Manhattan 66
   • 10-15 realistic documents per boat
   • 5 active warranties (2 expiring soon for demo)

3. Performance Testing (20 min)

   • Upload 50 documents (simulate broker workload)
   • Concurrent search queries (5 simultaneous users)
   • OCR processing queue handling
   • Database query optimization

4. Bug Fixing (30 min)

   • Review all agent outputs
   • Fix integration issues
   • Polish UI rough edges
   • Verify mobile responsiveness

Final Deliverable: Working demo ready for presentation

---

🚀 Deployment Sequence (Total: 3 hours)

Phase 1: Initial Setup (t=0 to t=20min)

All agents in parallel:

# On StackCP server
ssh stackcp

# Agent 1: Clone & setup backend
tmux new -s backend-dev
cd /tmp
git clone https://github.com/dannystocker/navidocs.git navidocs
cd /tmp/navidocs/server
/tmp/npm install --production
# Launch Claude Code CLI
/tmp/claude

# Agent 2: Setup frontend
tmux new -s frontend-dev
cd /tmp/navidocs/client
/tmp/npm install
# Launch Claude Code CLI
/tmp/claude

# Agent 3: Setup OCR
tmux new -s ocr-dev
cd /tmp/navidocs/server/services
# Launch Claude Code CLI
/tmp/claude

# Agent 4: Infrastructure
tmux new -s infra
cd /tmp/navidocs
# Launch Claude Code CLI
/tmp/claude

# Agent 5: QA
tmux new -s qa
cd /tmp/navidocs
mkdir -p tests
# Launch Claude Code CLI
/tmp/claude

Phase 2: Core Development (t=20min to t=120min)

Agents work in parallel following task priorities above.

Coordinator (you):

• Monitor tmux sessions every 15 minutes
• Check agent progress: tmux ls + attach to each session
• Resolve blockers immediately
• Coordinate handoffs between agents

Phase 3: Integration (t=120min to t=180min)

Agent 1 + Agent 2: Wire frontend to backend APIs Agent 3: Verify OCR working end-to-end Agent 4: All services running, monitoring active Agent 5: E2E tests passing, demo data loaded

Phase 4: Polish (t=180min to t=240min)

All agents: Bug fixes, UI polish, performance optimization Agent 5: Final QA pass, presentation rehearsal

Phase 5: Presentation Prep (t=240min to t=300min)

All agents: Standby mode, ready to fix issues Coordinator: Prepare talking points, demo script

---

📋 Agent Prompts (Copy-Paste into Claude Code CLI)

Agent 1: Backend Developer Prompt

You are Agent 1 (S2-BACKEND) for NaviDocs deployment on StackCP.

**Mission:** Build production-ready Express.js backend in 2 hours.

**Context:**
- Working dir: /tmp/navidocs/server
- Database: ~/navidocs-data/db/navidocs.db (SQLite)
- Architecture from: intelligence/session-2/session-2-architecture.md
- Sprint plan: intelligence/session-4/week-1-detailed-schedule.md

**Priority Tasks:**
1. Database setup + migrations (schema.sql already exists)
2. Core API endpoints:
   - POST /api/auth/register (email, password, name)
   - POST /api/auth/login (returns JWT)
   - POST /api/documents/upload (file upload + OCR queue)
   - GET /api/documents/list?boat_id=X
   - GET /api/warranties/expiring?days=30
3. Background worker: server/workers/ocr-worker.js
4. curl test all endpoints

**Constraints:**
- Code must run in /tmp (executable)
- Data must be in ~ (persistent)
- Use Redis Cloud for BullMQ (get creds from .env)
- Meilisearch at localhost:7700

**Output:** Working API on port 8001, database populated, worker running.

Start now!

Agent 2: Frontend Developer Prompt

You are Agent 2 (S2-FRONTEND) for NaviDocs deployment on StackCP.

**Mission:** Build production Vue 3 frontend in 2 hours.

**Context:**
- Working dir: /tmp/navidocs/client
- Design system: intelligence/session-3/agent-9-visual-design-system.md
- UI components needed:
  - Login/Register forms
  - Document upload interface
  - Document list with search
  - Warranty dashboard
  - Boat selector sidebar

**Priority Tasks:**
1. Core components (45 min):
   - Login.vue, Register.vue, DocumentUpload.vue, DocumentList.vue
2. Layout (30 min):
   - TopNav.vue, Sidebar.vue, MainLayout.vue
3. Build & deploy (15 min):
   - npm run build
   - cp -r dist/* ~/public_html/digital-lab.ca/navidocs/
4. Test UI flow (15 min)

**Design Guidelines:**
- Ocean Deep #003D5C (nav, headers)
- Wave Blue #0066CC (buttons, links)
- Sand Beige #F5F1E8 (backgrounds)
- Inter font family
- Mobile-first, responsive

**Output:** Working UI accessible at https://digital-lab.ca/navidocs

Start now!

Agent 3: OCR Integration Specialist Prompt

You are Agent 3 (S2-OCR) for NaviDocs deployment on StackCP.

**Mission:** Implement hybrid OCR system using Claude Code CLI + Google Vision API.

**Context:**
- Working dir: /tmp/navidocs/server/services
- Claude CLI: /tmp/claude (use for intelligent document analysis)
- Google Vision: @google-cloud/vision package

**Priority Tasks:**
1. Claude Code CLI OCR (30 min):
   - Create ocr-claude.js that uses /tmp/claude CLI
   - Extract: text + equipment names + dates + warranty periods
   - Structured output: { text, equipment: [], warranties: [], dates: [] }

2. Google Vision fallback (20 min):
   - Create ocr-google-vision.js for handwriting detection
   - Multi-page PDF processing

3. Hybrid orchestrator (20 min):
   - Create ocr-hybrid.js
   - Try Claude first (faster + context)
   - Fallback to Google Vision if needed

4. Test suite (20 min):
   - Typed PDF (warranty certificate)
   - Handwritten receipt
   - Multi-page manual

**Innovation:**
- Claude Code CLI can UNDERSTAND document context (not just OCR text)
- Extract equipment automatically: "Volvo Penta D6-370" from manual
- Detect warranty periods: "24 months from purchase date"

**Output:** OCR service that handles ALL document types with intelligence.

Start now!

Agent 4: Infrastructure & DevOps Prompt

You are Agent 4 (S2-INFRA) for NaviDocs deployment on StackCP.

**Mission:** Configure production infrastructure in 90 minutes.

**Context:**
- StackCP constraints: /tmp executable, ~ persistent
- Services needed: API server, OCR worker, Meilisearch indexer
- External: Redis Cloud, Google Vision API

**Priority Tasks:**
1. Environment config (15 min):
   - Create /tmp/navidocs/server/.env
   - Redis Cloud connection (free tier)
   - Google Vision API credentials
   - Meilisearch localhost:7700
   - JWT secret generation

2. Process management (20 min):
   - navidocs-api.sh (start Express on port 8001)
   - navidocs-worker.sh (start OCR worker)
   - Health check script (curl endpoints)

3. Apache reverse proxy (15 min):
   - ~/public_html/digital-lab.ca/navidocs/.htaccess
   - Proxy /api/* to http://localhost:8001/api/*
   - Serve static files from ~/public_html

4. Monitoring (15 min):
   - Centralized logging to ~/navidocs-data/logs/
   - Error tracking
   - Performance monitoring

**Output:** All services running, accessible at https://digital-lab.ca/navidocs

Start now!

Agent 5: QA & Integration Testing Prompt

You are Agent 5 (S2-QA) for NaviDocs deployment on StackCP.

**Mission:** End-to-end testing + demo data preparation in 2 hours.

**Context:**
- Working dir: /tmp/navidocs/tests
- Demo for: Riviera Plaisance (premium yacht broker)
- Presentation in 5 hours

**Priority Tasks:**
1. E2E test suite (45 min):
   - User flow: register → login → upload → search
   - Warranty tracking flow
   - Multi-boat organization
   - Mobile responsiveness

2. Demo data (30 min):
   - Organization: "Riviera Plaisance"
   - 3 boats: Azimut 55S, Princess V50, Sunseeker Manhattan 66
   - 10-15 documents per boat (manuals, warranties, receipts)
   - 5 warranties (2 expiring in 30 days for demo alert)

3. Performance testing (20 min):
   - Upload 50 documents
   - Concurrent searches (5 users)
   - OCR queue handling
   - Database query optimization

4. Bug fixing (30 min):
   - Review all agent outputs
   - Fix integration issues
   - Polish UI
   - Verify mobile

**Critical Success Factors:**
- €24K-€65K resale value recovery claim (works?)
- 19-25 hour time savings (visible in UI?)
- 98% documentation completeness (measure?)

**Output:** Flawless demo ready for Riviera meeting.

Start now!

---

🔧 Technical Stack (Final)

Component	Technology	Location	Status
Backend	Express.js (Node.js 20.18.0)	/tmp/navidocs/server	Deploy
Frontend	Vue 3 + Vite	/tmp/navidocs/client → ~/public_html	Deploy
Database	SQLite (better-sqlite3)	~/navidocs-data/db/navidocs.db	Create
Search	Meilisearch 1.6.2	localhost:7700	✅ Running
Queue	BullMQ + Redis Cloud	redis-*.redis.cloud:port	Setup
OCR Primary	Claude Code CLI (/tmp/claude)	/tmp/navidocs/server/services	Build
OCR Fallback	Google Vision API	@google-cloud/vision	Setup
Web Server	Apache (StackCP managed)	~/public_html	Configure

---

📊 Success Metrics (5 Hours)

Metric	Target	Actual	Status
API Endpoints	10+ working	TBD	Pending
Frontend Pages	5 core pages	TBD	Pending
OCR Success Rate	>90%	TBD	Pending
Upload Speed	<5 sec per doc	TBD	Pending
Search Latency	<200ms	TBD	Pending
Demo Data	3 boats, 30+ docs	TBD	Pending
Mobile Responsive	100%	TBD	Pending
Zero Errors	No console errors	TBD	Pending

---

🚨 Risk Mitigation

Risk 1: Redis Cloud Setup Delay

Mitigation: Use in-memory queue (fallback) Impact: OCR processing slower but works

Risk 2: Google Vision API Credentials Missing

Mitigation: Claude Code CLI only (primary OCR) Impact: Handwriting detection reduced

Risk 3: Agent Coordination Failure

Mitigation: Manual intervention every 15 min Impact: Slower progress but still functional

Risk 4: StackCP Resource Limits

Mitigation: Optimize heavy operations Impact: Reduce concurrent uploads to 3

---

📞 Quick Commands (Coordinator)

Monitor Agents

ssh stackcp
tmux ls                           # List all sessions
tmux attach -t backend-dev        # Check Agent 1
tmux attach -t frontend-dev       # Check Agent 2
tmux attach -t ocr-dev            # Check Agent 3
tmux attach -t infra              # Check Agent 4
tmux attach -t qa                 # Check Agent 5

Check Services

# API server
curl http://localhost:8001/api/health

# Meilisearch
curl http://localhost:7700/health

# Database
sqlite3 ~/navidocs-data/db/navidocs.db "SELECT COUNT(*) FROM documents;"

# Logs
tail -f ~/navidocs-data/logs/server.log
tail -f ~/navidocs-data/logs/worker.log

Emergency Restart

pkill -f "node server/index.js"
pkill -f "node workers/ocr-worker.js"
cd /tmp/navidocs/server
/tmp/node index.js > ~/navidocs-data/logs/server.log 2>&1 &
/tmp/node workers/ocr-worker.js > ~/navidocs-data/logs/worker.log 2>&1 &

---

✅ Final Checklist (Before Presentation)

• All 5 agents completed their tasks
• API responding on https://digital-lab.ca/navidocs/api/health
• Frontend accessible at https://digital-lab.ca/navidocs
• User can register → login → upload → search
• OCR processing working (test with 1 PDF)
• Warranty dashboard showing expiring items
• Demo data loaded (Riviera Plaisance + 3 boats)
• Mobile responsive (test on phone)
• No console errors in browser
• Presentation script reviewed

---

READY TO LAUNCH: Deploy in 3 hours, test in 1 hour, present in 1 hour.

MAXIMUM VELOCITY MODE: All agents start simultaneously, coordinator monitors every 15 min.

🚀 LET'S GO!