APP

the app for thoughts

4 hours ago

theunpartyapp (Web Platform)

Location: /Users/UNPARTYLLC/theunpartyapp/ (Repository: unparty-app/theunpartyapp)
Status: Active Development
Primary Purpose: Public-facing web application and content management platform for the UNPARTY ecosystem

Overview

theunpartyapp is the primary web presence for UNPARTY, serving as both a marketing platform and content management system. Built with Next.js 15 and TypeScript, it provides a comprehensive admin panel, content publishing system, and user engagement features while integrating with the broader UNPARTY ecosystem.

Tech Stack

Framework: Next.js 15.3.1 (App Router)
Language: TypeScript 5.8.3
Database: PostgreSQL via Prisma ORM 6.14.0
Authentication: Clerk (with dark theme support)
Payments: Stripe
Deployment: Vercel
Styling: Tailwind CSS 3.4.17 with custom theme system
Content: MDX support for rich content
File Storage: Vercel Blob
Analytics: Vercel Analytics & Speed Insights

Node.js: 20.19.4+ required
npm: 10.8.2+

Key Features

Content Management

Articles System: MDX-powered articles with slug-based routing and admin publishing workflow
Books Inventory: Book management system with claiming functionality and shipping fee tracking
Editorial System: Rich content editing with custom components
Media Management: SVG upload/management system with trash/restore functionality

Admin Panel

Horizontal Navigation: Modern admin interface with theme-aware active states
Step Management: Task/step system with categories, priorities, and progress tracking
User Submissions: File and form submission review system with admin workflow
Question Builder: Dynamic question system with multiple response types
Repository Explorer: Visual documentation pages for all UNPARTY repositories

User Experience

Custom Theme System: Global theme context with customizable color values
Marketing Pages: Landing pages showcasing UNPARTY products and vision
Waitlist System: User signup and token-based verification
Progress Tracking: Per-user step completion tracking

Developer Tools

Investigation Workflow: Comprehensive CLI for handling build failures and technical issues
Asset Generation: Automated icon and image manifest generation
Data Normalization: Page data processing and optimization
Type Safety: Full TypeScript coverage with Prisma type generation

Architecture

Code

Web App (Next.js 15 App Router)
├── Public Routes
│   ├── Marketing Pages (/about, /connect, /build)
│   ├── Article Display (/article/[slug])
│   ├── Repository Pages (/theunparty*)
│   └── Waitlist (/waitlist)
├── Protected Admin Routes
│   ├── /admin/articles (Content Management)
│   ├── /admin/books (Inventory)
│   ├── /admin/steps (Task Management)
│   ├── /admin/submissions (User Review)
│   ├── /admin/questions (Question Builder)
│   └── /admin/users (User Management)
├── API Routes (REST)
│   ├── /api/articles (CRUD operations)
│   ├── /api/book (Claiming & payments)
│   ├── /api/steps (Progress tracking)
│   ├── /api/upload-svg (Media management)
│   └── /api/waitlist (User signup)
├── Database (Prisma + PostgreSQL)
│   ├── Step (Tasks & categories)
│   ├── Article (Content)
│   ├── Book (Inventory)
│   ├── UserSubmission (Reviews)
│   └── UserStepProgress (Tracking)
└── File Storage (Vercel Blob)
    └── User uploads & media

Getting Started

Prerequisites

Node.js 20.19.4 or higher
npm 10.8.2 or higher
PostgreSQL database OR SQLite for development (see DATABASE_SETUP.md)
Clerk account for authentication
Stripe account for payments (optional for development)

Environment Setup

CRITICAL: The application requires a DATABASE_URL to build and run. Without it, deployment will fail with:

Error: Environment variable not found: DATABASE_URL.

📖 Complete Database Setup Guide: See DATABASE_SETUP.md for detailed instructions.

Quick Start:

Copy the environment template:
bash
cp .env.example .env.local
Set up your database:

Option A: SQLite (Easiest for local development)
bash
# Already configured in .env.example DATABASE_URL="file:./dev.db"
Option B: PostgreSQL (Production-like)
- Use Vercel Postgres, Supabase, Railway, or Neon
- Follow DATABASE_SETUP.md for step-by-step instructions
- Update DATABASE_URL in .env.local
Set up authentication (Clerk):
- Create account at clerk.com
- Get API keys from dashboard
- Update in .env.local:
bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key CLERK_SECRET_KEY=sk_test_your_key
Set up payments (optional for development):
- Create account at stripe.com
- Get test API key from dashboard
- Update in .env.local:
bash
STRIPE_SECRET_KEY=sk_test_your_key

Complete environment variable reference: See .env.example

Installation

bash

# Install dependencies (takes ~60 seconds)
npm install

# Generate Prisma client
npm run db:generate

# Push database schema (creates tables)
npm run db:push

# Seed database with initial data (optional)
npm run db:seed

Note: If npm run db:push fails, verify your DATABASE_URL is correctly set in .env.local.

Development

bash

# Start development server with Turbopack
npm run dev

# Server starts at http://localhost:3000 in ~3 seconds

Build

bash

# Full production build (requires valid environment variables)
npm run build

# Build includes:
# 1. Icon manifest generation
# 2. Image manifest generation  
# 3. Data normalization
# 4. Prisma client generation
# 5. Next.js compilation

Database Commands

bash

npm run db:generate    # Generate Prisma client (5 seconds)
npm run db:push        # Push schema changes to database
npm run db:migrate     # Run database migrations
npm run db:studio      # Open Prisma Studio GUI
npm run db:seed        # Seed database with initial data

Utility Scripts

bash

npm run generate-icons    # Generate icon manifest from public/svgs/
npm run generate-images   # Generate image manifest with dimensions
npm run normalize-data    # Process page metadata
npm run lint              # Run Next.js linter (~10 seconds)

Investigation Workflow

This project includes a comprehensive investigation workflow system for handling build failures, TypeScript errors, and technical issues systematically.

Quick Start

bash

# Initialize a new investigation
./scripts/investigate init typescript-errors admin-any-types

# Create System Investigation Template (SIT)
./scripts/investigate sit

# Create Technical Investigation Report (TIR)
./scripts/investigate tir

# Complete investigation and commit
./scripts/investigate complete

Investigation CLI Commands

Command	Purpose	Example
`init <category> <description>`	Start new investigation	`./scripts/investigate init build-errors dependency-conflicts`
`sit`	Generate System Investigation Template	`./scripts/investigate sit`
`tir`	Generate Technical Investigation Report	`./scripts/investigate tir`
`complete`	Commit investigation with standard message	`./scripts/investigate complete`
`list`	Show all investigations	`./scripts/investigate list`
`status`	Show current investigation progress	`./scripts/investigate status`

Workflow Process

Detection - Build failure or issue identified
Initialize - ./scripts/investigate init <category> <description>
System Analysis - ./scripts/investigate sit (creates SIT document)
Technical Analysis - ./scripts/investigate tir (creates TIR document)
Implementation - Follow TIR solution plan
Completion - ./scripts/investigate complete (commits with standard format)

Documentation

📋 Investigation Workflow Guide - investigation-workflow-guide.md
🔧 Git Integration Guide - investigation-workflow-git-integration.md
📊 System Investigation Template - system-investigation-template.md
🔍 Technical Investigation Report - technical-investigation-report.md

Investigation Directory Structure

Code

investigations/
├── 2025-06/
│   ├── system-investigation-2025-06-02-typescript-errors-admin-any-types.md
│   └── technical-investigation-report-2025-06-02-typescript-errors-admin-any-types.md
└── archive/

Git Integration

The workflow creates investigation branches following the pattern:

investigation/{YYYY-MM-DD}/{category}/{description}

Commits follow standardized format:

Code

Investigation: Complete {category} analysis

{INVESTIGATION_ID}
- SIT document created and reviewed
- TIR document created with solution
- Ready for implementation review

Database Models

Core Models

Step: Task/step management system

Categories, priorities, and due dates
Organization-based visibility
Progress tracking per user
Linked questions for user input

Article: Content management

Slug-based routing
Published/draft status
Category organization
MDX content support

Book: Inventory system

SKU-based tracking
Stock and condition management
User claiming with Stripe integration
Shipping fee and address handling

UserSubmission: User-generated content

File uploads via Vercel Blob
Form submissions
Admin review workflow
Status tracking (pending, approved, rejected)

Question: Dynamic questionnaire system

Multiple question types (text, choice, rating)
Step association
Audience targeting
Order management

Relationships

Code

Step 1---* Question
Step 1---* UserStepProgress
Question 1---* UserQuestionResponse
User 1---* UserStepProgress
User 1---* UserQuestionResponse
User 1---* UserSubmission
Book 1---1 User (via claimedBy)

Integration Points

External Services

Clerk: Authentication and user management

Dark theme integration
Protected admin routes
User session management

Stripe: Payment processing

Book claiming payments
Shipping fee handling
Payment status tracking

Vercel: Deployment and infrastructure

Blob storage for file uploads
Analytics and Speed Insights
Edge functions for API routes

Google APIs: Service integrations

Google Sheets integration
Service account authentication

Prisma: Database ORM

Type-safe database operations
Migration management
Schema-first development

Internal Integrations

Asset Management:

Automated icon manifest generation
Image dimension analysis
SVG organization system

Content Pipeline:

MDX compilation for articles
Gray-matter for frontmatter parsing
Custom component rendering

Business Value

ABOUT → BUILD → CONNECT Framework

ABOUT: Understanding and Discovery

Marketing pages showcase UNPARTY vision and products
Article system educates users on concepts and methodologies
Repository explorer pages document ecosystem relationships
Waitlist system captures early interest and feedback

BUILD: Creation and Development

Admin panel enables content creation without code
Step system guides users through structured processes
Investigation workflow helps developers solve technical problems
MDX support allows rich, interactive content creation

CONNECT: Sharing and Collaboration

User submission system enables community contributions
Question/response system facilitates user feedback
Book claiming connects readers with physical resources
Integration with broader UNPARTY ecosystem (runway, crawler, unppp)

Relationship to Ecosystem

Data Flow with Other Repositories

theunpartyrunway (Development Automation)

Receives cost tracking data from theunpartyapp development
Sprint calendar integration for planning
5 Gatekeepers methodology enforcement
Architecture decision documentation

theunpartycrawler (Analytics Intelligence)

Provides conversation analytics insights
Content processing for article optimization
Usage pattern analysis for feature prioritization

theunpartyunppp (Native App)

Shares user authentication via Clerk
Common design language and branding
Complementary journaling and content experiences

Integration Diagram

Code

┌─────────────────────────────────────────┐
│         theunpartyapp (Web)             │
│                                         │
│  Marketing + Content + Admin Panel      │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┼─────────┐
        │         │         │
        ▼         ▼         ▼
   ┌────────┐ ┌──────┐ ┌────────┐
   │ Clerk  │ │Stripe│ │ Vercel │
   │  Auth  │ │ Pay  │ │  Blob  │
   └────────┘ └──────┘ └────────┘
        │         │         │
        └─────────┼─────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ runway  │ │crawler  │ │  unppp  │
   │(DevOps) │ │(Analytics)│(Native) │
   └─────────┘ └─────────┘ └─────────┘

Build Process & Validation

Build Timing (CRITICAL)

Dependencies: npm install takes ~60 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
Linting: npm run lint takes ~10 seconds. Always passes with warnings.
Type Checking: npx tsc --noEmit takes ~15 seconds. NEVER CANCEL.
Database: npm run db:generate takes ~5 seconds for Prisma client generation.
Development: npm run dev starts in ~3 seconds with Turbopack.
Production Build: npm run build fails without valid environment variables.

Validation Steps

ALWAYS run before committing:

bash

npm run lint                 # 10 seconds, identifies React hooks warnings
npx tsc --noEmit            # 15 seconds, validates TypeScript  
npm run db:generate         # 5 seconds, updates Prisma client
npm run generate-icons      # 2 seconds, updates icon manifest
npm run generate-images     # 2 seconds, updates image manifest

Manual Testing Scenarios

Development Server:

Run npm run dev and verify http://localhost:3000 starts
Expect Clerk authentication errors without valid keys

Build System Testing:

Test icon/image generation: npm run generate-icons && npm run generate-images
Verify Prisma generation: npm run db:generate
Type checking: npx tsc --noEmit

Investigation Workflow:

Test CLI: ./scripts/investigate --help
Create test investigation: ./scripts/investigate init test-category test-description

Common Issues & Troubleshooting

Build Failures

❌ Missing DATABASE_URL

Error: Environment variable not found: DATABASE_URL.

Solution: Set up a database and configure DATABASE_URL. See DATABASE_SETUP.md for detailed instructions.

For local development:

bash

# In .env.local
DATABASE_URL="file:./dev.db"

For deployment:

Create a PostgreSQL database (Vercel Postgres, Supabase, etc.)
Add DATABASE_URL to Vercel environment variables
See DEPLOYMENT.md

❌ Missing Environment Variables

Add required variables to .env.local (local) or Vercel dashboard (deployment):

bash

# Minimum required for build
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
DATABASE_URL="file:./dev.db"

❌ Invalid Clerk Keys

Get valid keys from Clerk Dashboard:

Development: Use test keys (pk_test_..., sk_test_...)
Production: Use live keys (pk_live_..., sk_live_...)

❌ Prisma Issues

Regenerate Prisma client:

bash

npm run db:generate

If schema changes aren't applying:

bash

npm run db:push  # Development
# or
npm run db:migrate  # With migration files

❌ Asset Generation

Run manifest generation scripts:

bash

npm run generate-icons
npm run generate-images

Expected Warnings

The build produces expected warnings (not errors):

React hooks dependency warnings in admin pages
Image optimization suggestions (use next/image)
Tailwind CSS class order warnings
ESLint code improvement suggestions

These warnings do not prevent the application from running.

Contributing

Quality Standards

Always run linting and type checking before committing
Use investigation workflow for systematic problem-solving
Follow existing code patterns and component structures
Update documentation when adding new features
Maintain minimal, surgical changes to existing code

Testing

Note: No automated test suite currently configured. Validation is done through:

TypeScript type checking
ESLint linting
Manual testing in development server
Build verification

Setup & Deployment

DATABASE_SETUP.md - Complete database setup guide for all environments
DEPLOYMENT.md - Step-by-step deployment instructions
VERCEL_ENV_SETUP.md - Environment variables quick reference
.env.example - Environment variables template with examples

Features & Systems

CLAUDE.md - AI assistance guidance for development
investigation-workflow-guide.md - Detailed workflow documentation
ARTICLE_CREATION.md - Article system guide
BOOK_SYSTEM_MIGRATION.md - Book inventory documentation
EDITORIAL_SYSTEM.md - Editorial content guide
PAGE_CREATION_README.md - Page creation workflows
VISUAL_HIERARCHY_SYSTEM.md - Design system documentation

Ecosystem Documentation

theunpartyrunway/docs/architecture/ - Swift app architecture evolution
theunpartyrunway/CLAUDE.md - Automation framework guide
theunpartyunppp/CLAUDE.md - Native app development guide
theunpartycrawler/CLAUDE.md - Analytics intelligence guide
theunpartycrawler/README.md - Crawler setup and usage

Project Structure

Code

theunpartyapp/
├── src/app/                    # Next.js App Router
│   ├── about/                  # Marketing pages
│   ├── admin/                  # Admin panel
│   │   ├── articles/           # Content management
│   │   ├── books/              # Inventory management
│   │   ├── steps/              # Task management
│   │   ├── submissions/        # User review
│   │   └── users/              # User administration
│   ├── api/                    # REST API routes
│   ├── article/[slug]/         # Article display
│   ├── components/             # Reusable UI components
│   ├── contexts/               # React contexts (theme, etc.)
│   ├── theunparty*/            # Repository documentation pages
│   └── waitlist/               # User signup
├── prisma/                     # Database
│   ├── schema.prisma           # Database schema
│   ├── migrations/             # Migration history
│   └── seed.ts                 # Initial data
├── public/                     # Static assets
│   ├── svgs/                   # SVG icons
│   ├── covers/                 # Cover images
│   └── fonts/                  # Custom fonts
├── scripts/                    # Build and utility scripts
│   ├── investigate             # Investigation CLI
│   ├── generate-icon-manifest.js
│   ├── generate-image-manifest.js
│   └── normalize-page-data.js
├── investigations/             # Investigation documents
├── .github/workflows/          # CI/CD pipelines
│   ├── typecheck.yml           # Automated TypeScript checking
│   └── claude.yml              # CI/CD configuration
└── [config files]              # next.config.ts, tsconfig.json, etc.

Deployment

Vercel Deployment

This application is optimized for Vercel deployment.

📖 Complete Deployment Guide: See DEPLOYMENT.md for detailed instructions.

Quick Steps:

Set up production database (see DATABASE_SETUP.md)
Connect repository to Vercel
Configure environment variables in Vercel dashboard:
- DATABASE_URL - REQUIRED (deployment will fail without this)
- NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Required
- CLERK_SECRET_KEY - Required
- STRIPE_SECRET_KEY - Required for payments
Deploy automatically on push to main branch

Environment Variables on Vercel

Critical (Build will fail without these):

DATABASE_URL - PostgreSQL connection string
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Clerk publishable key
CLERK_SECRET_KEY - Clerk secret key

Required for functionality:

STRIPE_SECRET_KEY - Stripe API key

Optional:

SLACK_TOKEN
GOOGLE_SHEETS_ID
GOOGLE_SERVICE_ACCOUNT_EMAIL

How to add: Vercel Dashboard → Project → Settings → Environment Variables

⚠️ Important: Select all environments (Production, Preview, Development) when adding variables.

Database Migrations

Automatic (Recommended):

bash

# Included in build process
npm run build
# Runs: prisma migrate deploy && prisma generate && next build

Manual (if needed):

bash

# For production
npx prisma migrate deploy

# For development
npm run db:migrate

See also:

DATABASE_SETUP.md - Database configuration
DEPLOYMENT.md - Complete deployment guide
VERCEL_ENV_SETUP.md - Environment variables reference

GitHub Workflows

typecheck.yml: Automated TypeScript checking

Runs on push to main and pull requests
Creates GitHub issues for TypeScript errors
Provides detailed error reporting

claude.yml: CI/CD pipeline

Build verification
Environment validation
Deployment triggers

Security & Privacy

Core Principles

Creator Ownership: Users own their content and data
Privacy First: Minimal data collection, transparent usage
Cost Sensitivity: Efficient resource usage, no surprise charges

Implementation

Clerk authentication with secure session management
Stripe PCI-compliant payment processing
Vercel Blob secure file storage
PostgreSQL with Prisma parameterized queries
Environment variable protection for secrets

Security Note: Never commit real API keys. Use test keys for development and environment variables for production.

Ecosystem Metrics

Total UNPARTY Repositories: 36 (4 documented, 32 pending)
theunpartyapp Status: Active Development
Primary Languages: TypeScript, JavaScript
Target Platform: Web (Desktop & Mobile Responsive)
Integration Services: Clerk, Vercel, Stripe, Prisma, Google APIs

Maintenance

Last Updated: 2025-10-29
Maintained By: GitHub Copilot CLI + Development Team
Review Frequency: Continuous updates with each feature addition

Learn More

Next.js Resources

Next.js Documentation - Learn about Next.js features and API
Learn Next.js - Interactive Next.js tutorial
Next.js GitHub - Feedback and contributions

UNPARTY Resources

UNPARTY Ecosystem Overview - Complete repository index
UNPARTY Vision - Product philosophy and goals

Focus: Measurable user progress through ABOUT → BUILD → CONNECT while protecting creator ownership, privacy, and cost-sensitivity.

Status: 🚀 Active Development (Core platform for UNPARTY ecosystem)

APP

theunpartyapp (Web Platform)

Content Management

Admin Panel

User Experience

Developer Tools

Code

Prerequisites

Environment Setup

bash

bash

bash

bash

Installation

bash

Development

bash

Build

bash

Database Commands

bash

Utility Scripts

bash

Quick Start

bash

Investigation CLI Commands

Investigation Categories

Workflow Process

Documentation

Investigation Directory Structure

Code

Git Integration

Code

Core Models

Relationships

Code

External Services

Internal Integrations

ABOUT → BUILD → CONNECT Framework

Data Flow with Other Repositories

Integration Diagram

Code

Build Timing (CRITICAL)

Validation Steps

bash

Manual Testing Scenarios

Build Failures

bash

bash

bash

bash

bash

Expected Warnings

Quality Standards

Testing

Setup & Deployment

Features & Systems

Ecosystem Documentation

Code

Vercel Deployment

Environment Variables on Vercel

Database Migrations

bash

bash

Core Principles

Implementation

Next.js Resources

UNPARTY Resources