← Back to Documentation Hub Timeline & Decisions

Project Timeline - Mad Monkey Project

Project: "Where Has Benny Been?" - Decision History & Milestones

Jump to: Key Decisions Architecture Evolution Domain Strategy Security Decisions Card Design Deployment Phases

Key Decision Timeline

November 2024
ARCHITECTURE

Project Inception & Core Concept

Decision: Build gamified QR code campaign "Where Has Benny Been?"

  • Goal: Email list growth through physical-to-digital engagement
  • Mechanism: QR codes on business cards distributed at venues
  • Incentive: Monthly contest for free tee-shirt
  • Technology: Self-hosted FOSS stack (n8n, PostgreSQL, Listmonk, Shlink)

Rationale: More engaging than traditional "sign up for newsletter" - creates story and interaction

December 1, 2024
ARCHITECTURE

Technology Stack Selection

Decision: Use n8n for workflow automation instead of custom code

Alternatives Considered:
  • Custom Node.js/Express API
  • Zapier (SaaS, monthly cost)
  • Make.com (limited free tier)
  • n8n (SELECTED) - Self-hosted, visual, extensible
Rationale: n8n provides visual workflow building, easy debugging, and self-hosted control without vendor lock-in
December 5, 2024
ARCHITECTURE

Database Selection: PostgreSQL 16

Decision: Use PostgreSQL as single shared database for all services

Alternatives Considered:
  • MySQL/MariaDB
  • MongoDB (document store)
  • SQLite (too limited for production)
  • PostgreSQL 16 (SELECTED)
Rationale: Mature, JSONB support for flexible schemas, native UUID, excellent with n8n and Listmonk
December 8, 2024
DOMAIN

Short URL Domain Selection

Decision: Register mmlnk.us for short URLs

Requirements:
  • Short and memorable
  • Recognizable brand connection (MM = Mad Monkey)
  • .us TLD for geographic association
  • Available domain
Rationale: "mmlnk" clearly indicates Mad Monkey link, .us TLD is cheaper and available
December 10, 2024
DESIGN

Card Type Strategy: Nest vs Traveler

Decision: Create two card types with different behaviors

Type Quantity Behavior Move Code
Nest Cards 200-300 Stationary at venues No
Traveler Cards 50-100 Mobile, passed person-to-person Yes

Rationale: Nest cards provide consistent local engagement, travelers create viral spread and storytelling opportunities

December 12, 2024
ARCHITECTURE

Email Platform: Listmonk

Decision: Self-host Listmonk instead of using SaaS email provider

Alternatives Considered:
  • Mailchimp (expensive at scale, $20-300/mo)
  • SendGrid (complex pricing)
  • Brevo (300 emails/day free limit)
  • Listmonk (SELECTED) - Self-hosted, unlimited
Cost Analysis:
  • Listmonk: $0/mo (self-hosted) + SMTP relay costs
  • Mailchimp: $20-60/mo for 500-2,500 subscribers
Rationale: Data ownership, no per-subscriber costs, API control, privacy-first
December 15, 2024
DOMAIN

Domain Consolidation Strategy

Decision: Abandon multi-subdomain approach under mmc.fit

Original Plan:
  • list.mmc.fit - Listmonk UI
  • benny.mmc.fit - Landing page
  • mmlnk.us - Short URLs
New Strategy:
  • mmlnk.us - Short URLs only (public)
  • mad-monkey-creations.com/benny - Landing page (subpath)
  • hooks.mad-monkey-creations.com - n8n webhooks (internal)
  • mail.mad-monkey-creations.com - Email server
Rationale: Simpler DNS, fewer SSL certificates, better branding consistency
December 18, 2024
ARCHITECTURE

Email Provider Switch: Brevo → ForwardMail.net

Decision: Use ForwardMail.net instead of Brevo for SMTP relay

Comparison:
Feature Brevo ForwardMail.net
Free Tier 300 emails/day More generous
Deliverability Good Excellent
Setup Moderate Simple
Rationale: Better reputation, simpler integration, recommended by email experts
December 19, 2024
DESIGN

Landing Page Hosting Decision

Decision: Host at /benny subpath instead of separate container

Options:
  • Separate Docker container on 10.0.0.154
  • Subpath on main site (SELECTED)
Rationale: Simpler deployment, shared SSL certificate, can migrate later if needed
December 20, 2024
DESIGN

QR Code Format: Dual SVG + PNG

Decision: Generate both SVG and PNG formats

Format Strategy:
  • SVG: Primary for print (infinite scaling)
  • PNG: Backup at 300 DPI (universal compatibility)
Rationale: Flexibility for different printers, ensures quality regardless of vendor
December 21, 2024
DESIGN

Card Design Differentiation

Decision: Create distinct back designs for nest vs traveler cards

Nest Card Back:
  • QR code
  • Short URL
  • Simple CTA: "Scan. Tell us where. Confirm email. Monthly winner!"
Traveler Card Back:
  • QR code
  • Short URL
  • CTA + move instructions
  • Prominent move code section
Rationale: Prevents confusion, clear user instructions, emphasizes move mechanic for travelers
December 22, 2024
SECURITY

Port 25 Blocked - SMTP Relay Decision

Discovery: Comcast ISP blocks outbound port 25 (SMTP)

Decision: Accept SMTP relay as permanent solution

Options Evaluated:
  • Use relay (SELECTED): ForwardMail.net on port 587/465
  • Upgrade to business ISP (expensive, $80-150/mo)
  • Move to VPS/cloud (adds complexity)
  • Request port unblock from ISP (rarely successful)
Rationale: Relay provides better deliverability anyway, cost-effective, works around ISP limitation
December 23, 2024
SECURITY

Privacy & Data Minimization

Decision: Implement strict data minimization policies

Privacy Measures:
  • IP Anonymization: Remove last octet before storage
  • No PII: Only collect email, name, city (user-reported)
  • Double opt-in: Required for all entries
  • Easy unsubscribe: One-click in every email
  • Data retention: 24 months for inactive subscribers
Rationale: GDPR-aware, builds trust, reduces liability, ethical approach
December 24, 2024
SECURITY

Rate Limiting & Abuse Prevention

Decision: Multi-layer rate limiting strategy

Rate Limits:
Endpoint Limit Window Key
/scan 10 requests 1 minute IP address
/entry 3 submissions 1 hour Email
/entry 1 entry 30 days Email + month
Additional Protections:
  • CAPTCHA for suspicious patterns
  • VPN/proxy detection
  • Device fingerprinting (optional)
Rationale: Prevent spam/abuse while allowing legitimate participation
December 26, 2024
PROCESS

Deployment Phase Strategy

Decision: Six-phase gradual rollout

Phases:
  1. Phase 1: Infrastructure (DNS, databases, containers)
  2. Phase 2: n8n workflows and testing
  3. Phase 3: QR production (10 test cards)
  4. Phase 4: End-to-end testing
  5. Phase 5: Pilot launch (20-50 cards)
  6. Phase 6: Full deployment (200-300 cards)
Rationale: De-risk launch, catch issues early, validate assumptions before scaling
January 1, 2026
ARCHITECTURE

Consolidation to Single Docker Host

Decision: Move from multi-server architecture to single Docker host

Architecture Change:
Component Old IP New Location
PostgreSQL 10.0.0.151 10.0.0.250:5432
n8n 10.0.0.198 10.0.0.250:5678
Shlink 10.0.0.152 10.0.0.250:8081
Listmonk 10.0.0.153 10.0.0.250:9000
New Infrastructure:
  • Single Docker host: bennybeen (10.0.0.250)
  • External IP: 76.150.65.61 (dynamic)
  • User: bennybeen (not indigoadmin)
  • Project path: /home/bennybeen/mad-monkey/
  • Admin whitelist: 10.0.0.157
Domain Updates:
  • Added: n8n.janness.com
  • Added: traefik.janness.com
  • Kept: hooks.mad-monkey-creations.com, mmlnk.us, admin.mmlnk.us, list.mad-monkey-creations.com
Email Service Changes:
  • Removed: All Brevo (Sendinblue) references
  • Kept: ForwardMail.net as ONLY email provider
  • Reason: Better deliverability, PostgreSQL integration, webhooks, API
Deployment:
  • Use deploy.sh script for automated deployments
  • n8n workflows available for deployment automation
  • DNS-UPDATE-PROCESS.md for handling dynamic IP changes
Rationale: Simplified architecture, easier management, reduced complexity, single point of administration. Trade-off: single point of failure, but acceptable for initial launch with proper backup procedures.

Architecture Evolution

Version 1.0: Initial Concept (November 2024)

Components: Limitations: No automation, manual processes, limited analytics

Version 2.0: n8n Integration (December 1-10, 2024)

Added: Improvements: Automated workflows, better analytics, scalable

Version 3.0: Current Architecture (December 15-Present)

Refinements: Status: Architecture finalized, ready for implementation

Domain Strategy Evolution

Version Date Strategy Status
V1 Nov 2024 Multiple subdomains under mmc.fit (list., benny.) Abandoned
V2 Dec 10, 2024 Hybrid: mmlnk.us + mmc.fit subdomains Abandoned
V3 (Current) Dec 15, 2024 Two domains: mmlnk.us + mad-monkey-creations.com subpaths Active

Final Domain Map

mmlnk.us: mad-monkey-creations.com:

Security Decision Timeline

December 18, 2024

HTTPS Everywhere

Decision: All services require SSL/TLS via Let's Encrypt

  • Traefik handles automatic certificate renewal
  • HTTP requests redirect to HTTPS
  • 90-day certificates, auto-renew at 60 days
December 22, 2024

Admin Endpoint Restrictions

Decision: IP whitelist for admin endpoints

  • admin.mmlnk.us/rest → Shlink API (IP-restricted)
  • Listmonk admin UI on internal network only
  • PostgreSQL not exposed externally
December 23, 2024

API Key Rotation Policy

Decision: Rotate API keys every 90 days

  • Shlink API keys
  • Listmonk credentials
  • n8n webhook secrets
  • External API keys (Printify, Etsy)
December 24, 2024

Database Backup Strategy

Decision: Daily automated backups with encryption

  • Daily PostgreSQL dumps at 3 AM
  • Encrypted with GPG
  • 30-day retention
  • Off-site backup to cloud storage
  • Monthly backup restoration tests

Card Design Evolution

Design Iteration History

Version Date Changes Reason
V1 Nov 2024 Single card type, QR + URL only Initial concept
V2 Dec 5, 2024 Added move code to all cards Enable traveler tracking
V3 Dec 10, 2024 Split into Nest vs Traveler types Different use cases require different features
V4 (Final) Dec 21, 2024 Distinct back designs, clear CTAs Reduce user confusion, improve clarity

Final Card Specifications

Physical: Visual Design:

Deployment Phase Timeline

Phase 1: Infrastructure Setup

IN PROGRESS

Timeline: December 26, 2024 - January 10, 2025 (estimated)

Status: 35% complete

Phase 2: n8n Workflow Creation

PLANNED

Timeline: January 11-20, 2025 (estimated)

Phase 3: QR Card Production (Test Batch)

PLANNED

Timeline: January 21-31, 2025 (estimated)

Phase 4: End-to-End Testing

PLANNED

Timeline: February 1-7, 2025 (estimated)

Phase 5: Pilot Launch

PLANNED

Timeline: February 8-28, 2025 (estimated)

Scale: 20-50 cards at 10-15 local venues

Phase 6: Full Deployment

PLANNED

Timeline: March 1, 2025+ (estimated)

Scale: 200-300 cards across region

Changes in Approach

Major Pivots & Course Corrections

1. From Custom Code to n8n

Original Plan: Build custom Node.js API with Express

Change: Use n8n for visual workflow automation

Impact: Faster development, easier debugging, more maintainable

2. From Multiple Subdomains to Two-Domain Strategy

Original Plan: list.mmc.fit, benny.mmc.fit, mmlnk.us

Change: mmlnk.us + mad-monkey-creations.com subpaths

Impact: Simplified DNS, better UX, clearer branding

3. From Self-Hosted SMTP to SMTP Relay

Original Plan: Direct email delivery from self-hosted server

Change: Relay through ForwardMail.net

Impact: Better deliverability, workaround ISP port blocking

4. From Single Card Type to Nest + Traveler

Original Plan: One card design for all use cases

Change: Separate designs optimized for stationary vs mobile

Impact: Clearer user instructions, better tracking, richer story

5. From Big Bang Launch to Phased Rollout

Original Plan: Print 300 cards and deploy all at once

Change: Six-phase gradual rollout starting with 10 test cards

Impact: Lower risk, catch issues early, validate assumptions