Wakeve is a collaborative event planning application for groups that need one place to decide when to meet, who is coming, what the plan is, and what still needs organizing. It combines Kotlin Multiplatform shared logic, Android Compose, native SwiftUI iOS, a Ktor backend, offline-first persistence, and Swarm DAO backlog governance.

The project is beyond the original Phase 2/Phase 3 README plan. Current source-of-truth tracking lives in ROADMAP.md and the Swarm DAO backlog (.dao/). | add-on-device-wakeve-ai | 40/41 tasks | Supported physical-device profiling for Foundation Models latency, cancellation, memory, and production-log privacy. |

Recent archived roadmap work includes Android AI workflows, Android adaptive UI, contact participant selection, scenario matrix voting, web microfrontends, account deletion, UGC moderation, iOS brand identity, and create-event slot previews.

✅ Event Organization

• Create events with multiple time slot options
• Invite participants and manage RSVPs
• Real-time availability polling
• Weighted voting system (YES=2, MAYBE=1, NO=-1)
• Automatic best-time calculation
• Offline-first database persistence
• DRAFT → POLLING → CONFIRMED → ORGANIZING → FINALIZED workflow coordination

✅ Virtual Meetings

• MeetingService with support for Zoom, Google Meet, FaceTime
• Secure meeting link generation via backend proxy
• Meeting invitation and reminder scheduling
• Integration with native calendar
• Meeting lifecycle management (create, update, cancel, start, end)

✅ Multiplatform Support

• Android with Jetpack Compose UI
• iOS with native SwiftUI app, shared KMP integration, App Store readiness evidence, and WeatherKit/WakeveAI work in progress
• JVM/Desktop support
• Single shared codebase via Kotlin Multiplatform

✅ Backend Infrastructure

• Production-ready Ktor REST API
• SQLDelight type-safe database
• Event, meeting, auth, moderation, calendar, and organization APIs
• Role-based access control
• Secure API key management for external platforms

✅ Release Readiness

• App Store blocker register and final signoff workflow
• Local privacy, accessibility, media, license, export, live URL, and Store metadata evidence docs
• Account deletion and UGC moderation implementations archived after local validation
• Critical release gate scripts for iOS metadata, web, and selected regression tests

# Clone repository
git clone https://github.com/guyghost/wakeve.git
cd wakeve

# Build and test
./gradlew build
./gradlew :shared:jvmTest

# Start server
./gradlew server:run   # http://localhost:8080

# Android uses https://api.wakeve.app by default.
# For emulator-local backend development, add this to local.properties:
# server.url=http://10.0.2.2:8080

# Build Android app
./gradlew :composeApp:assembleDebug

See QUICK_START.md for detailed setup instructions.

wakeve/
├── shared/               # Kotlin Multiplatform shared code
│   ├── src/commonMain/  # Cross-platform models & logic
│   ├── src/jvmTest/     # JVM-specific tests
│   └── sqldelight/      # Type-safe database schema
├── composeApp/          # Android app with Jetpack Compose
├── server/              # Ktor REST backend server
├── iosApp/              # Native iOS app and Xcode project
└── docs/                # Documentation

┌─────────────────────────────────────┐
│  UI Layer (Compose/SwiftUI)         │
├─────────────────────────────────────┤
│  Business Logic (EventRepository)   │
├─────────────────────────────────────┤
│  Persistence (SQLDelight)           │
├─────────────────────────────────────┤
│  Platform Drivers (Android/iOS/JVM) │
└─────────────────────────────────────┘

Wakeve follows the Functional Core, Imperative Shell pattern to ensure testability and separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                    IMPERATIVE SHELL                  │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Services (MeetingService, EventRepository)      │  │
│  │  State Machines (MVI FSM)                      │  │
│  │  External APIs (MeetingProxyRoutes)              │  │
│  └───────────────────────────────────────────────────┘  │
│  Handles side effects: I/O, async, state mutations   │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│                     FUNCTIONAL CORE                   │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Pure Functions (logic, validators, transforms)  │  │
│  │  Domain Models (Event, Meeting, Vote)           │  │
│  │  Business Rules (scoring, eligibility)           │  │
│  └───────────────────────────────────────────────────┘  │
│  No side effects, 100% testable                      │
└─────────────────────────────────────────────────────────┘

Key Principles:

• ✅ Shell CAN call Core
• ✅ Core CANNOT call Shell
• ✅ Core ignores Shell's existence
• ✅ Pure functions in Core are easily testable
• ✅ Side effects isolated in Shell (database, network, API)

See docs/architecture/meeting-service.md for detailed MeetingService architecture.

• Language: Kotlin 2.2.20 with Multiplatform support
• UI: Jetpack Compose (Android), SwiftUI (iOS)
• Database: SQLDelight with type-safe queries
• Backend: Ktor 3.3.1 REST server
• Testing: Kotlin test, XCTest, release gate scripts
• Serialization: kotlinx-serialization for JSON

• QUICK_START.md - 5-minute setup guide
• CONTRIBUTING.md - Development guidelines
• AGENTS.md - Swarm DAO workflow and AI agents

For comprehensive documentation, visit docs/:

• Architecture - System architecture and KMP patterns
• API Documentation - REST API endpoints
• Testing - Testing strategy and reports
• Integrations - Calendar, OAuth, and external services
• Migration Guides - Design system migrations
• Refactoring Docs - Major refactorings
• Implementation Status - PRD feature tracking

• Java 11+
• Kotlin 2.2.20
• Gradle 8.14+
• Android SDK (for Android development)
• Xcode with an available iOS simulator (for iOS development)

# Run shared JVM tests
./gradlew :shared:jvmTest

# Run specific test
./gradlew :shared:jvmTest --tests "EventRepositoryTest"

# Build Android app
./gradlew :composeApp:assembleDebug

# Start server
./gradlew :server:run

# Format code
./gradlew spotlessApply

Wakeve has comprehensive test coverage:

EventRepositoryTest          10 tests
PollLogicTest               6 tests
DatabaseEventRepositoryTest 13 tests
OfflineScenarioTest         7 tests
───────────────────────────────────
Unit Tests                  36 tests ✅

PrdWorkflowE2ETest          6 tests
ServiceIntegrationE2ETest    5 tests
MultiUserCollaborationTest   10 tests
DeleteEventE2ETest           6 tests
AuthFlowE2ETest              4 tests
───────────────────────────────────
E2E Tests                  35 tests ✅

TOTAL                      71 tests ✅

All tests cover:

• ✅ Event creation and lifecycle
• ✅ Participant management
• ✅ Vote submission and aggregation
• ✅ Database persistence
• ✅ Offline data recovery
• ✅ API endpoints
• ✅ Complete PRD workflow (DRAFT → FINALIZED)
• ✅ Multi-user collaboration scenarios
• ✅ Virtual meeting link generation
• ✅ Service integration (Budget, Transport, Meeting, Suggestion)

GET    /health                    # Health check
GET    /api/events                # List all events
GET    /api/events/{id}           # Get event details
POST   /api/events                # Create event
PUT    /api/events/{id}/status    # Update event status
GET    /api/events/{id}/participants   # List participants
POST   /api/events/{id}/participants   # Add participant
GET    /api/events/{id}/poll      # Get poll results
POST   /api/events/{id}/poll/votes    # Submit vote

POST   /api/meetings/proxy/zoom/create              # Create Zoom meeting
POST   /api/meetings/proxy/google-meet/create       # Create Google Meet meeting
POST   /api/meetings/proxy/zoom/{id}/cancel        # Cancel Zoom meeting
GET    /api/meetings/proxy/zoom/{id}/status        # Get Zoom meeting status

Security Note: Meeting proxy endpoints secure external API keys (Zoom, Google Meet) by handling all external API calls server-side.

See docs/API/meeting-api.md for detailed MeetingProxy API documentation.

WAKEVE_API_BASE="${WAKEVE_API_BASE:-https://api.wakeve.app}"

curl -X POST "$WAKEVE_API_BASE/api/events" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team Meeting",
    "description": "Q4 Planning",
    "organizerId": "user-1",
    "deadline": "2025-11-20T18:00:00Z",
    "proposedSlots": [{
      "id": "slot-1",
      "start": "2025-12-01T10:00:00Z",
      "end": "2025-12-01T12:00:00Z",
      "timezone": "UTC"
    }]
  }'

• OAuth/email/guest authentication flows in shared and platform code
• Role-based access control for organizer and participant behavior
• Account deletion flow implemented and locally validated
• UGC moderation, reporting, blocking, and review controls implemented and archived
• Store-readiness checks for privacy manifests, logging hygiene, live URL/AASA evidence, App Review notes, and release signoff markers

• UI Framework: Jetpack Compose
• Target: API 24+
• Build: ./gradlew :composeApp:assembleDebug

• Framework: SwiftUI with shared KMP framework integration
• Project: iosApp/iosApp.xcodeproj
• Target: tracked in Xcode build settings
• Database: Native SQLite driver

• Framework: Ktor REST server
• Database: SQLDelight with JDBC driver
• Run: ./gradlew server:run

1. Create feature branch: codex/<feature-name> for Codex work
2. Follow the Swarm DAO proposal process for significant changes (see CONTRIBUTING.md)
3. Write tests for all new code
4. Submit PR with issue reference

<type>(optional-scope): <description>

<optional body>

Examples:

feat(events): add event creation API
fix(timezone): handle poll slot conversion
test(sync): add offline conflict scenarios

Build Fails

./gradlew clean build  # Clean rebuild
java -version          # Verify Java 11+

Tests Failing

./gradlew :shared:jvmTest --info  # Verbose output
./gradlew :shared:jvmTest --tests "TestName" -d  # Debug mode

Server Won't Start

lsof -i :8080          # Check port 8080
./gradlew :server:run --info  # Debug mode

See QUICK_START.md for more solutions.

Wakeve follows the Swarm DAO governance process for the backlog:

1. dao_propose → 2. dao_deliberate → 3. dao_check →
4. dao_plan → 5. dao_execute → 6. dao_ship → 7. dao_rate

See AGENTS.md for the detailed workflow.

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Code style guidelines
• Testing requirements
• Commit conventions
• Pull request process

• Issues: Create GitHub Issue for bugs/features
• Discussions: Use GitHub Discussions for questions
• Documentation: See full docs in repository
• Email: Contact maintainers for security issues

Wakeve is licensed under the MIT License. See LICENSE file for details.

Built with:

• Kotlin Multiplatform
• Jetpack Compose
• Ktor
• SQLDelight

Wakeve's mission is to make collaborative scheduling effortless. By combining intelligent polling, automatic scheduling, and offline-first principles, we're building the event planning tool for distributed teams.

Ready to contribute? Start with QUICK_START.md and CONTRIBUTING.md!

Questions? Check docs/ for detailed documentation.