Hey there! 👋 Tap & Tell is a modern, NFC-powered digital guestbook that transforms how guests leave their mark at events. Guests tap their phone on an NFC tag (or scan a QR code), and a beautiful multi-step wizard guides them through leaving their name, photo, and a personal message. No app install required! 📱✨

Perfect for weddings 💍, birthday parties 🎂, corporate events 🏢, or any gathering where you want to capture memories digitally!

The magic is simple — here's the flow:

1. 📲 Guest taps NFC tag or scans QR code
         ↓
2. 🌐 Browser opens Tap & Tell (no app install!)
         ↓
3. 🧙 4-step wizard collects:
      Step 1: Name + Photo (required)
      Step 2: Favorites — color, food, movie, song, video (optional)
      Step 3: Fun Facts — superpowers, hidden talents, preferences (optional)
      Step 4: Personal Message (required)
         ↓
4. 💾 Entry saved with photo compression
         ↓
5. 🎉 Entry appears in the guestbook!

Ready to set up your own digital guestbook? Let's go! 🎉

• Node.js 18+ installed
• pnpm package manager (npm install -g pnpm)

# 1. Clone the repo
git clone https://github.com/Disane87/tap-and-tell.git
cd tap-and-tell

# 2. Install dependencies
pnpm install

# 3. Start the dev server
pnpm dev

That's it! Open http://localhost:3000 and you're running! 🎉

Create a .env file in the project root:

# PostgreSQL connection string
POSTGRES_URL=postgresql://user:password@localhost:5432/tapandtell

# JWT signing secret (CHANGE THIS in production!)
JWT_SECRET=your-jwt-secret-here

# CSRF token signing secret (CHANGE THIS in production!)
CSRF_SECRET=your-csrf-secret-here

# Master encryption key for photo encryption (64 hex chars, REQUIRED in production!)
ENCRYPTION_MASTER_KEY=

# Storage directory for entries and photos
DATA_DIR=.data

Prefer containers? We've got you covered!

The docker-compose.prod.yml is a self-contained stack (app + PostgreSQL) ready for Portainer or any Docker host.

1. Generate secrets

All secrets must be set before first start. Generate them with openssl:

# JWT signing secret (64-char hex)
openssl rand -hex 32

# CSRF token secret (64-char hex)
openssl rand -hex 32

# Photo encryption master key (64-char hex)
openssl rand -hex 32

# PostgreSQL password (64-char hex)
openssl rand -hex 32

# API token secret (base64)
openssl rand -base64 32

2. Configure environment variables

Set the generated values in docker-compose.prod.yml or pass them as environment variables:

3. Deploy

# Direct Docker Compose
docker compose -f docker-compose.prod.yml up -d

Or in Portainer: Stacks → Add Stack → paste the compose file → set environment variables in the UI.

docker compose up -d

# Build the image
docker build -t tap-and-tell .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e POSTGRES_URL=postgresql://user:password@host:5432/tapandtell \
  -e DB_SSL=false \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -e CSRF_SECRET=$(openssl rand -hex 32) \
  -e ENCRYPTION_MASTER_KEY=$(openssl rand -hex 32) \
  -e TOKEN_SECRET=$(openssl rand -base64 32) \
  -v tap-and-tell-data:/app/data \
  tap-and-tell

Here's a tour of everything Tap & Tell offers:

The main entry point for guests! Features:

• 🎠 Swipeable Carousel — Intro slide followed by existing entry slides
• 📝 Bottom Sheet Wizard — The 4-step form slides up from the bottom
• ⌨️ Keyboard & Swipe Navigation — Navigate entries with arrow keys or swipe gestures
• 📱 NFC Context Detection — Personalized welcome when entering via NFC tag
• 🔵 Pagination Dots — Visual indicators for carousel position

Browse all approved entries in a beautiful grid:

• 🔍 Search by Name — Debounced search (300ms) for instant filtering
• 🔄 Sort Options — Newest first or oldest first
• 📄 PDF Export — Download the entire guestbook as a formatted PDF
• 🖥️ Slideshow Link — Quick access to slideshow mode
• 👆 Detail View — Click any card to see the full entry in a bottom sheet

Perfect for displaying on a TV at your event!

• ▶️ Auto-Advancing — Configurable interval (3–30 seconds, default 8)
• ⏸️ Play/Pause Controls — Take control when you want
• 🖥️ Fullscreen Mode — True fullscreen for maximum impact
• ⌨️ Keyboard Controls — Arrow keys, Space, P (pause), F (fullscreen), ESC (exit)
• 👻 Auto-Hide Controls — Controls fade away during playback

Manage your guestbook with a password-protected admin panel:

• 📊 Status Tabs — Filter by All, Pending, Approved, Rejected
• ✅ Bulk Actions — Approve or reject multiple entries at once
• 🗑️ Individual Management — Delete or change status of single entries
• 🔢 Entry Counts — See counts per status at a glance
• 🚪 Secure Logout — Token-based session management

Generate QR codes for your event:

• 🎯 Custom Event Name — Embed your event name in the URL
• 📥 Download Options — Export as PNG or SVG
• 📋 Copy URL — Quick copy to clipboard
• 🔗 NFC-Compatible URLs — Generates ?source=nfc&event=YourEvent links

Let's peek under the hood! Here's how Tap & Tell is built:

tap-and-tell/
├── app/                          # 🖥️ Nuxt client application
│   ├── pages/                    #    Route pages
│   ├── components/               #    Vue components
│   │   ├── form/                 #    Wizard form steps
│   │   └── ui/                   #    shadcn-vue base components
│   ├── composables/              #    Vue composables (state & logic)
│   ├── types/                    #    TypeScript type definitions
│   ├── plugins/                  #    Nuxt client plugins
│   ├── layouts/                  #    Page layouts
│   ├── lib/                      #    Utility functions
│   └── assets/                   #    Static assets (CSS, images)
│
├── server/                       # ⚙️ Nitro server
│   ├── routes/api/               #    API endpoints
│   │   ├── g/                    #    Public guest endpoints (flat routes)
│   │   ├── auth/                 #    Authentication + 2FA
│   │   ├── tenants/              #    Tenant/guestbook management
│   │   └── photos/               #    Photo serving (encrypted)
│   ├── database/                 #    Schema + migrations (Drizzle ORM)
│   ├── utils/                    #    Server utilities (crypto, auth, storage)
│   └── plugins/                  #    Server startup plugins
│
├── i18n/                         # 🌍 Internationalization
│   └── locales/                  #    EN + DE translation files
│
├── public/                       # 📂 Static public assets
│   └── icons/                    #    PWA icons
│
├── plans/                        # 📋 Development plan documents
├── nuxt.config.ts                # ⚙️ Nuxt configuration
├── package.json                  # 📦 Dependencies
└── tsconfig.json                 # 🔧 TypeScript config

Tap & Tell uses PostgreSQL 16+ with Row-Level Security (RLS) for multi-tenant data isolation. Photos are stored on disk with AES-256-GCM per-tenant encryption.

PostgreSQL (via Drizzle ORM)
├── users, sessions, user_two_factor     # Auth & 2FA
├── tenants, tenant_members              # Multi-tenancy
├── guestbooks, entries                  # Core data (RLS-protected)
└── audit_logs, api_apps, api_tokens     # Security & API access

.data/photos/
├── [guestbookId]/[entryId].[ext]        # AES-256-GCM encrypted photos
└── ...

All API endpoints at a glance. Authenticated endpoints use HTTP-only JWT cookies with CSRF protection.

# Login
curl -X POST /api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
# → Sets access_token and refresh_token cookies

# Create a guest entry (public, no auth)
curl -X POST /api/g/your-guestbook-id/entries \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "message": "What an amazing event!",
    "photo": "data:image/jpeg;base64,..."
  }'

The brain of Tap & Tell lives in these composables — each one handles a specific concern:

Tap & Tell features a 3-layer theme initialization to prevent any flash of unstyled content (FOUC):

Layer 1: Inline <script> in <head>
  └─ Runs BEFORE first paint
  └─ Reads localStorage, applies `dark` class to <html>
  └─ Zero visual flash! ⚡

Layer 2: Client Plugin (theme.client.ts)
  └─ Syncs reactive Vue state with DOM
  └─ Listens for system preference changes

Layer 3: <ClientOnly> Wrapper
  └─ ThemeToggle component only renders on client
  └─ Prevents SSR hydration mismatches

Toggle between Light ☀️, Dark 🌙, and System 💻 modes with a single click.

All user-facing text is translatable — no hardcoded strings anywhere!

Translation files live in i18n/locales/ covering all scopes: form, guestbook, admin, navigation, slideshow, toasts, and more.

Setting up NFC tags or QR codes for your event is easy!

1. Get writable NFC tags (NTAG215 or similar)
2. Use any NFC writer app to write the URL:

   https://your-domain.com/?source=nfc&event=YourEventName
   

3. Place tags at your event venue — guests tap and they're in! 📲

1. Go to /admin/qr in your admin panel
2. Enter your event name
3. Download as PNG or SVG
4. Print and display at your venue! 🖨️

Here's what a guest entry looks like under the hood:

interface GuestEntry {
  id: string                    // UUID
  name: string                  // Guest's name
  message: string               // Personal message
  photoUrl?: string             // Photo path (e.g., /api/photos/{id}.jpg)
  answers?: GuestAnswers        // Optional form answers
  createdAt: string             // ISO 8601 timestamp
  status?: EntryStatus          // 'pending' | 'approved' | 'rejected'
  rejectionReason?: string      // Why entry was rejected
}

interface GuestAnswers {
  // 🎨 Favorites
  favoriteColor?: string
  favoriteFood?: string
  favoriteMovie?: string
  favoriteSong?: { title: string; artist?: string; url?: string }
  favoriteVideo?: { title: string; url?: string }

  // 🎭 Fun Facts
  superpower?: string
  hiddenTalent?: string
  desertIslandItems?: string
  coffeeOrTea?: 'coffee' | 'tea'
  nightOwlOrEarlyBird?: 'night_owl' | 'early_bird'
  beachOrMountains?: 'beach' | 'mountains'

  // 📖 Our Story
  howWeMet?: string
  bestMemory?: string
}

Want to contribute or customize? Here's how to get the development environment running:

pnpm install              # Install dependencies
pnpm dev                  # Start development server (https://localhost:3000)
pnpm build                # Build for production
pnpm preview              # Preview production build locally
pnpm exec nuxi typecheck  # Run TypeScript type checking

Here are the "why"s behind the design:

Want to make Tap & Tell even better? That's awesome! 🎉

Here's how to get started:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💻 Make your changes
4. ✅ Build to verify (pnpm build)
5. 📝 Commit with conventional commits (feat: add amazing feature)
6. 🚀 Push and open a Pull Request

• 🔤 Code comments & JSDoc in English
• 🌍 All user-facing text must use i18n translation keys
• 🎨 Styling with Tailwind CSS utility classes
• 🧩 UI components follow shadcn-vue conventions
• ♿ Accessibility (a11y) best practices
• 📝 TypeScript — avoid any type
• 🔒 Security — no hardcoded secrets, validate at boundaries

We use Conventional Commits:

feat: add new feature
fix: resolve a bug
docs: update documentation
refactor: restructure code
style: formatting changes
test: add or update tests
chore: maintenance tasks

Here are some creative ways to use Tap & Tell:

• 💍 Weddings — Let guests leave their wishes and photos for the couple
• 🎂 Birthday Parties — Collect fun facts and memories from attendees
• 🏢 Corporate Events — Gather feedback and networking connections
• 🎓 Graduations — Classmates share their favorite memories
• 🎄 Holiday Parties — Guests share their holiday traditions and wishes
• 🏠 Housewarming — Visitors leave advice and well-wishes for the new home
• 🎸 Concerts & Festivals — Fans share their experience and favorite moments

Thanks for checking out Tap & Tell! If you find it useful, give it a ⭐ on GitHub — it really helps! 🙌

Got a bug to report? Have an idea for a new feature? Open an issue and let's make this better together! 🚀

Made with ❤️ using Nuxt, Vue, and Tailwind CSS