Last updated: Aug 4, 2025, 11:26 AM UTC

NudgeCampaign MVP - Service Access Guide

Status: Generated Post-Build
Purpose: Complete guide for accessing all system services and admin interfaces
Build Version: build-v1

System Overview

NudgeCampaign MVP consists of multiple interconnected services. This guide provides access URLs, credentials, and configuration instructions for all components.

Main Application

NudgeCampaign Web App

  • URL: http://localhost:3001
  • Access: Direct browser access
  • Purpose: Main user interface for campaign management
  • Status: Fully functional

Available Pages:

Database Services

Supabase Database

  • PostgreSQL Direct Access: localhost:54322
  • Status: Running via Docker
  • Admin Interface: Supabase Studio not running (Docker image version issues)

Database Access:

# Direct PostgreSQL connection
Host: localhost
Port: 54322
Database: postgres
Username: postgres
Password: postgres

Database Connection String:

postgresql://postgres:postgres@localhost:54322/postgres

Supabase Admin Interface:

  • Status: NOT ACCESSIBLE - Docker container failed to start
  • Issue: Supabase Studio image versions incompatible
  • Alternative: Use direct PostgreSQL connection or tools like pgAdmin, DBeaver, etc.
  • Expected URL: http://localhost:54323 (when working)

Alternative Database Access Methods:

  1. Command Line: psql postgresql://postgres:postgres@localhost:54322/postgres
  2. pgAdmin: Connect using the credentials above
  3. DBeaver: Database management tool
  4. VS Code Extensions: PostgreSQL client extensions

Key Tables:

  • users - User accounts and profiles
  • campaigns - Email campaign data
  • contacts - Contact management
  • automations - n8n workflow tracking

Automation Services

n8n Workflow Automation

  • URL: http://localhost:5678
  • Access: Direct browser access
  • Purpose: Visual workflow automation builder
  • Status: Requires initial setup

Current Issues:

❌ 401 Unauthorized errors in application logs
❌ No initial workflows configured
❌ Authentication may need configuration

Setup Instructions Needed:

  1. Access n8n at http://localhost:5678
  2. Complete initial setup wizard
  3. Configure authentication credentials
  4. Import or create initial workflows
  5. Test workflow execution

Integration Points:

Email Services

Postmark Email Service

  • Provider: External SaaS (postmarkapp.com)
  • Purpose: Transactional email delivery
  • Status: Requires account configuration

Account Information Needed:

Postmark Account: [User needs to provide]
Server Token: [To be configured in environment]
From Domain: knowcode.tech (configured)
From Email: lindsay@knowcode.tech (configured)

Configuration Status:

  • Environment Variable: POSTMARK_API_TOKEN (needs setting)
  • From Address: lindsay@knowcode.tech
  • Message Stream: marketing
  • Domain: knowcode.tech

Setup Instructions:

  1. Create Postmark account at https://postmarkapp.com
  2. Set up sender signature for knowcode.tech domain
  3. Get server token from Postmark dashboard
  4. Update environment variable: POSTMARK_API_TOKEN=your_token_here
  5. Test email delivery through application

MailDev (Development Email Testing)

  • URL: http://localhost:1080
  • Purpose: Local email testing and debugging
  • Status: Available for development

Features:

  • View all outgoing emails
  • Debug email formatting
  • Test email delivery without external service

Development Tools

Docker Container Management

  • Tool: Docker Desktop or docker-compose
  • Config File: docker-compose.yml
  • Purpose: Manage all service containers

Container Status Check:

# View running containers
docker ps

# View container logs
docker-compose logs [service-name]

# Restart services
docker-compose restart [service-name]

Available Services:

  • nudgecampaign-app - Main Next.js application
  • supabase-db - PostgreSQL database
  • supabase-studio - Database admin interface
  • n8n - Workflow automation engine
  • maildev - Development email server

API Endpoints

Application APIs

Available Endpoints:

GET  /api/campaigns          - List campaigns
POST /api/campaigns          - Create campaign  
GET  /api/campaigns/[id]     - Get campaign details
❌   PUT  /api/campaigns/[id]     - Update campaign (NOT IMPLEMENTED)
DELETE /api/campaigns/[id]   - Delete campaign

GET  /api/contacts           - List contacts
POST /api/contacts           - Create contact
GET  /api/contacts/[id]      - Get contact details  
❌   PUT  /api/contacts/[id]      - Update contact (NOT IMPLEMENTED)
DELETE /api/contacts/[id]    - Delete contact

GET  /api/automations        - List n8n workflows
POST /api/automations/welcome-series - Create welcome workflow

GET  /api/system-test        - System health check
POST /api/test-email         - Send test email

Security & Access

Authentication Status:

  • Current: Hardcoded demo user (DEMO_USER_ID)
  • Missing: Supabase Auth integration
  • Required: Multi-tenant user management

Admin Access Needed:

  • User Management: No admin portal implemented
  • Subscription Management: Not implemented
  • System Configuration: Via Docker and environment variables

Configuration Files

Environment Variables (.env.local):

# Database
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=[from Supabase dashboard]
DATABASE_URL=postgresql://postgres:your-super-secret-and-long-postgres-password@localhost:54322/postgres

# Email
POSTMARK_API_TOKEN=[needs configuration]

# n8n
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=[needs configuration]  
N8N_BASIC_AUTH_PASSWORD=[needs configuration]

Docker Configuration (docker-compose.yml):

  • Database passwords and ports
  • Service networking configuration
  • Volume mounts for data persistence

Known Issues & Setup Required

Critical Setup Tasks:

  1. Supabase Studio Admin Interface:

    • BROKEN: Docker image version incompatible (supabase/studio:20231123-ce42139 not found)
    • Fix Docker image versions for Supabase services
    • Alternative: Use external database tools (pgAdmin, DBeaver) to access PostgreSQL
    • Direct database access working on port 54322

  2. Postmark Email Service:

    • Create Postmark account
    • Configure sender domain verification
    • Set POSTMARK_API_TOKEN environment variable

  3. n8n Automation Platform:

    • Complete initial setup wizard at http://localhost:5678
    • Configure authentication (admin/password)
    • Create initial workflows
    • Test workflow execution

  4. Multi-Tenant Authentication:

    • Enable Supabase Auth
    • Create user signup/login flows
    • Implement admin portal
    • Remove hardcoded demo user

  5. Edit Functionality:

    • Implement campaign editing
    • Implement contact editing
    • Create edit forms and API endpoints

Quick Start Checklist

For Immediate Use:

For Production Setup:

  • Configure Postmark email service
  • Set up n8n authentication and workflows
  • Enable Supabase Auth for multi-tenancy
  • Implement missing edit functionality
  • Create admin portal for user management

External Service Dependencies

Required External Accounts:

  1. Postmark (https://postmarkapp.com) - Email delivery
  2. Supabase (https://supabase.io) - Database hosting (for production)
  3. Domain Management - For email domain verification

Optional External Services:

  • n8n Cloud - Hosted automation (alternative to self-hosted)
  • Monitoring Services - Application performance monitoring
  • CDN Services - Static asset delivery

📞 Support & Troubleshooting

Common Issues:

n8n 401 Unauthorized:

  • Access http://localhost:5678 and complete setup
  • Configure authentication credentials
  • Restart containers if needed

Email Not Sending:

  • Check Postmark configuration
  • Verify POSTMARK_API_TOKEN is set
  • Use MailDev for local testing

Database Connection Issues:

  • Verify Docker containers are running
  • Check database credentials in .env.local
  • Restart Supabase container if needed

Log Files:

  • Application Logs: dev-server.log
  • Docker Logs: docker-compose logs [service]
  • Browser Console: For frontend debugging

This service access guide should have been automatically generated during the autonomous build process. Framework v2 will ensure complete operational documentation is provided with every build.