Unparty Logo

UNPPP

the iOS app to shut up and unppp

theunpartyunppp (Native Application)

Status: Active Development
Primary Purpose: iOS native journaling and personal intelligence application
Platform: iOS 18.1+
Version: 3030

Overview

theunpartyunppp (pronounced "unppp") is a SwiftUI-based iOS application that provides a comprehensive journaling experience with AI-powered insights, semantic search, and intelligent content transformation. The app follows a local-first architecture with JSON-based persistence, having recently migrated away from CloudKit to ensure user privacy and data ownership.

Tech Stack

  • Framework: SwiftUI
  • Language: Swift 5.0
  • Architecture: MVVM with Dependency Injection
  • Database: Local-first (JSON Files + SwiftData)
  • Platform: iOS 18.1+
  • Build Tool: Xcode
  • Authentication: Auth0 + Biometric (Face ID/Touch ID)
  • Key Dependencies:
    • SwiftData for structured data
    • Combine for reactive programming
    • Core Data for legacy thought storage
    • LocalStorageManager for JSON persistence

Key Features

1. Journal Management

  • Create, edit, and delete journal entries
  • Rich text support with media attachments
  • Cover image customization
  • Word statistics and analytics
  • Journal circles for categorization
  • Search with intelligent caching

2. Ideas System

  • Transform journal entries into actionable ideas
  • Context-based photo selection
  • Idea requirements and validation
  • Storage management with LocalStorageManager

3. Chat Interface

  • AI-powered chat with semantic search
  • Message history and threading
  • Pinecone integration for context retrieval
  • Error handling with graceful fallbacks

4. Analytics & Insights

  • Word usage analysis
  • Writing pattern recognition
  • Mood tracking and visualization
  • Timeline-based insights
  • Performance analytics

5. User Experience

  • Dark/Light/System appearance modes
  • Adaptive navigation (tab bar/sidebar)
  • Party animations and celebrations
  • Custom UnpartyLogger system
  • Biometric authentication
  • Privacy-first design

6. Content Organization

  • Priority system for content
  • Community organization features
  • Task management
  • Feature evaluation system
  • Document storage

Architecture

High-Level Structure

Code

Native App (SwiftUI)
├── AppSources/              # Core application code
│   ├── uappApp.swift       # App initialization & DI
│   ├── LocalStorageManager.swift  # JSON persistence layer
│   ├── MODELS/             # Data models & stores
│   ├── Journal/            # Journal feature
│   ├── Ideas/              # Ideas feature
│   ├── User/               # User management
│   └── API/                # External API clients
├── TableofContents/         # Feature modules
│   ├── UserJournal/        # Journal UI & logic
│   ├── Ideas/              # Ideas UI & logic
│   ├── UserChat/           # Chat interface
│   ├── Analytics/          # Analytics dashboard
│   ├── Logger/             # UnpartyLogger system
│   ├── UnpartyDashboard/   # Main dashboard
│   └── Settings/           # App settings
├── ContentCommons/          # DEPRECATED - Legacy code
├── api/                     # Python services
│   └── unparty/            # Embedding & Pinecone scripts
└── scripts/                 # Build & analysis utilities

Data Flow Architecture (Post-CloudKit Migration)

Code

┌─────────────────────────────────────────────────────┐
│              SwiftUI Views                          │
│  (UserJournal, Ideas, Chat, Dashboard)              │
└──────────────────┬──────────────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────────────┐
│           ViewModels (@MainActor)                   │
│  JournalViewModel, IdeaViewModel, ChatViewModel     │
└──────────────────┬──────────────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────────────┐
│              Store Layer                            │
│  JournalStore, IdeaStorageManager, ThoughtStore     │
└──────────────────┬──────────────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────────────┐
│         LocalStorageManager                         │
│  - JSON file I/O                                    │
│  - Data caching                                     │
│  - Directory management                             │
└──────────────────┬──────────────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────────────┐
│         Local File System                           │
│  ~/Documents/journals/, ~/Documents/ideas/          │
└─────────────────────────────────────────────────────┘

Dependency Injection Pattern

All ViewModels are created in AppSources/uappApp.swift and injected via SwiftUI environment:

swift

// In uappApp.swift
@StateObject private var journalViewModel: JournalViewModel
@StateObject private var ideaViewModel: IdeaViewModel
@StateObject private var tocViewModel: ToCViewModel

// In Views
@EnvironmentObject var journalViewModel: JournalViewModel

Data Model

Core Entities

Journal

  • ID: String (UUID)
  • Title: String
  • Content: String (rich text)
  • Created: Date
  • Modified: Date
  • Cover: String (image reference)
  • Circle: String (category)
  • Word Count: Int
  • Media: Array of JournalMedia references

Idea

  • ID: String (UUID)
  • Title: String
  • Description: String
  • Source: Journal reference (optional)
  • Requirements: Array of validation criteria
  • Context: Photos and metadata
  • Status: String (draft, active, completed)

Thought (Core Data - Legacy)

  • Content: String
  • Timestamp: Date
  • Category: String

Integration Points

External Services

  1. Pinecone (Semantic Search)

    • Embedding storage and retrieval
    • Chat context enhancement
    • Idea similarity matching
    • Accessed via Vercel API endpoints

  2. Auth0 (Authentication)

    • User identity management
    • OAuth flows
    • Configuration in Auth0.plist

  3. Vercel API (Backend Services)

    • Pinecone operations
    • Embedding generation
    • Chat completions

  4. Python Services (api/unparty/)

    • Embedding generation
    • Data upsert scripts
    • Batch processing utilities

Internal Integration

  • UnpartyLogger: Custom logging system with categories (.system, .ui, .network, .data, .general, .performance, .auth)
  • Analytics Service: Content analysis and insights
  • Theme Manager: Appearance customization
  • Navigation Coordinator: App-wide navigation state

Development Workflow

Setup

bash

# Clone the repository
git clone https://github.com/unparty-app/theunpartyunppp.git
cd theunpartyunppp

# Open in Xcode
open uapp.xcodeproj

# Install SwiftLint (if not installed)
brew install swiftlint

Build Commands

bash

# Build for iOS Simulator (recommended for development)
xcodebuild -project uapp.xcodeproj -scheme uapp \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' build

# Run tests
xcodebuild -project uapp.xcodeproj -scheme uapp \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' test

# Lint code
swiftlint lint --path AppSources

# Find unbuild Swift files
./find-unbuild-swift-files.sh

# Validate implementation
./validate_implementation.sh

Code Quality

  • Linting: SwiftLint with custom rules (see .swiftlint.yml)
  • Documentation: Required for all public APIs
  • Testing: Unit tests in uappTests/
  • Force Unwrapping: Treated as error - use safe unwrapping
  • Naming: PascalCase for types, camelCase for properties/functions

Common Build Warnings (Expected & Non-Blocking)

  • Swift 6 actor isolation warnings (main actor property access)
  • Deprecated UIScreen.main usage warnings
  • Asset catalog color space transform warnings

Custom Logging System

Use UnpartyLogger instead of print():

swift

// Basic logging
uLog("General message", category: .general)
uDebug("Debug info", category: .system)
uError("Error occurred", category: .network)
uWarning("Warning message", category: .ui)
uSuccess("Success message", category: .data)

// Performance tracking
uStart("Operation name", category: .performance)
uSuccess("Operation completed", category: .performance)

// Celebration logging
uParty("APP LAUNCHED!")

Categories: .system, .ui, .network, .data, .general, .performance, .auth

Migration Notes

CloudKit to Local-First Architecture

The app recently completed a major migration from CloudKit to local-only storage:

Changes Made:

  • ✅ Replaced CKRecord.ID with String UUIDs
  • ✅ Created LocalStorageManager for JSON persistence
  • ✅ Migrated JournalViewModel to local storage patterns
  • ✅ Updated all data access to use Store layer
  • ✅ Removed CloudKit sync dependencies
  • ✅ Implemented SwiftData for structured local data

Architecture Principles:

  • Local-first: All data stored on device
  • Privacy-focused: No cloud sync required
  • JSON files: Human-readable, portable
  • SwiftData: Type-safe structured data
  • Cache layer: Performance optimization

Legacy Code:

  • ⚠️ Some CloudKit references may exist in peripheral code
  • 🚫 ContentCommons/ directory is DEPRECATED - do not add new code
  • ✅ Always use LocalStorageManager for persistence

Business Value

ABOUT - Understanding

  • Personal Insights: Analytics reveal writing patterns and mood trends
  • Semantic Search: Find relevant content across journals and ideas
  • Word Statistics: Track vocabulary usage and writing evolution
  • Timeline Analysis: Understand personal growth over time

BUILD - Creation

  • Journaling: Capture thoughts with rich text and media
  • Idea Generation: Transform journal entries into actionable ideas
  • Task Management: Organize and track personal goals
  • Context Preservation: Maintain connections between related content

CONNECT - Sharing

  • Privacy First: All data stored locally, user controls sharing
  • Export Capabilities: JSON format for data portability
  • Community Features: Organize content for selective sharing
  • Chat Interface: AI-powered conversations with context awareness

Relationship to UNPARTY Ecosystem

Data Flow with Other Repositories

Integration with Other UNPARTY Repositories

  1. theunpartyapp (Web)

    • Potential future web companion
    • Shared content patterns
    • Consistent branding

  2. theunpartyrunway (Dev Tools)

    • Cost tracking for API usage
    • Architecture documentation (15 Mermaid diagrams)
    • Sprint velocity measurement
    • Development workflow automation

  3. theunpartycrawler (Analytics)

    • Conversation pattern analysis
    • Usage insights and optimization
    • Content processing intelligence

Testing Strategy

Test Structure

Code

uappTests/
├── ViewModelTests/      # Business logic tests
├── StoreTests/          # Data layer tests
├── ModelTests/          # Data model tests
└── ServiceTests/        # API & service tests

Testing Approach

  • ViewModels: Test published properties and business logic
  • Stores: Test data persistence and retrieval
  • Services: Mock external dependencies
  • UI: Preview-based validation

Running Tests

bash

# All tests
xcodebuild -project uapp.xcodeproj -scheme uapp \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' test

# Specific test
xcodebuild -project uapp.xcodeproj -scheme uapp test \
  -only-testing:uappTests/<TestClass>/<testFunction>

Documentation

Key Documentation Files

  • CLAUDE.md: AI assistance guidance for development
  • README.md: This file - comprehensive overview
  • .github/copilot-instructions.md: GitHub Copilot guidance
  • docs/: Component documentation and screenshots
  • Architecture Docs (in theunpartyrunway):
    • 15 Mermaid diagrams documenting evolution
    • Journal/Owner/Media model decisions
    • Search feature implementation
    • User layer persistence design

Investigation Workflows

The app uses structured investigation templates:

  • System Investigation Templates (SIT)
  • Technical Investigation Reports (TIR)
  • Git-integrated tracking
  • Standardized commit messages

Privacy & Security

Privacy-First Design

  • Local Storage: All data stored on device
  • No Cloud Sync: User controls all data
  • Biometric Auth: Face ID / Touch ID protection
  • Auth0 Integration: Secure authentication flows
  • Data Portability: JSON export capability

Security Features

  • Biometric Authentication: Lock app with Face ID/Touch ID
  • Secure Storage: Encrypted local file system
  • No Analytics Tracking: User data never leaves device
  • Auth0 OAuth: Industry-standard authentication

Cost Sensitivity

API Usage Optimization

  • Local-First: Minimize external API calls
  • Caching: Intelligent search result caching
  • Batch Operations: Efficient bulk updates
  • Pinecone: Semantic search only when needed

Development Cost Tracking

Integration with theunpartyrunway for:

  • Claude API cost analysis
  • Pinecone usage monitoring
  • Development velocity correlation
  • Sprint-based cost allocation

Contributing

Before Making Changes

  1. Review CLAUDE.md for development guidelines
  2. Review .github/copilot-instructions.md for architecture patterns
  3. Understand the local-first architecture
  4. Check SwiftLint rules in .swiftlint.yml
  5. Use UnpartyLogger for all logging

Code Style

  • Follow SwiftLint rules
  • Document all public APIs
  • Use dependency injection patterns
  • Never force unwrap optionals
  • Use descriptive variable names
  • Organize code with extensions

Commit Guidelines

  • Use structured commit messages
  • Reference issue numbers
  • Keep commits focused and atomic
  • Test before committing

Troubleshooting

Build Issues

"My Mac" destination warning

  • ✅ Always use iOS Simulator destination
  • ❌ Avoid "My Mac" - causes compatibility warnings

Multiple destinations warning

  • Always specify -destination explicitly in build commands

SwiftLint failures

  • Run swiftlint lint --path AppSources to see issues
  • Fix errors before committing

Common Issues

ContentCommons deprecation errors

  • Move code to AppSources/ or TableofContents/
  • Never add new code to ContentCommons/

CloudKit references

  • Use LocalStorageManager instead
  • Follow local-first patterns

Force unwrapping errors

  • Use optional chaining or guard statements
  • Never use ! for unwrapping

Roadmap

Current Focus (Q4 2025)

  • ✅ Complete CloudKit to local-first migration
  • ✅ Implement LocalStorageManager
  • ✅ Update all ViewModels to local patterns
  • 🚧 Deprecate ContentCommons module
  • 🚧 Enhanced analytics dashboard
  • 🚧 Improved chat context management

Future Considerations

  • Web companion integration (theunpartyapp)
  • Cross-device sync (optional, user-controlled)
  • Enhanced AI features
  • Advanced analytics visualizations
  • Community sharing features (privacy-first)

Support & Resources

Documentation

Related Repositories

  • theunpartyapp: Web platform and marketing
  • theunpartyrunway: Development automation and intelligence
  • theunpartycrawler: Analytics and conversation intelligence

Metrics

Current State (as of 2025-10-29)

MetricValue
Version3030
iOS Target18.1+
Primary LanguageSwift 5.0
ArchitectureLocal-First MVVM
Main FeaturesJournal, Ideas, Chat, Analytics
Test CoverageUnit tests in uappTests/
Code QualitySwiftLint enforced

Maintenance

Last Updated: 2025-10-29
Maintained By: UNPARTY LLC
Status: 🚀 Active Development

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

License

Copyright © 2025 UNPARTY LLC. All rights reserved.