Demo screenshot with complete conversation and proposed schedule

Clarity: Transforming Chaos into Clarity

Inspiration

The inspiration hit us considering our own hectic student schedules. We were drowning in the same problem every student and professional faces: calendars that show what we're doing, but never help us design how we should live.

Picture this: It's 2 AM, you're staring at your Google Calendar, manually dragging events around trying to figure out how to fit in that exam prep, club meeting, and still get 8 hours of sleep. Sound familiar? That's when we realized the fundamental flaw in modern calendar tools — they're just digital whiteboards, not intelligent assistants.

We asked ourselves: What if your calendar could think? What if it could understand your goals and automatically redesign your week to align with what truly matters?

What It Does

Clarity is an AI-powered calendar assistant that transforms your chaotic schedule into an optimized, balanced life. Instead of manually dragging events around, you simply talk to your calendar:

"Add NSBE every Tuesday at 6 PM" → Automatically scheduled with smart conflict resolution
"Shift my meetings so I can attend office hours tomorrow" → Intelligent reshuffling that respects your priorities
"Optimize my week to maximize study time while still getting 8 hours of sleep" → Complete schedule redesign based on your goals

Key Features:

Conversational Interface: Natural language scheduling through voice and text
Visual Comparison: Side-by-side "before vs. after" calendar views
Smart Optimization: AI considers sleep, focus time, deadlines, and personal preferences
Real-time Sync: Changes automatically apply to your Google Calendar
Conflict Resolution: Intelligent handling of scheduling conflicts and constraints

How We Built It

We architected a full-stack AI-powered scheduling system with four core pillars:

1. RESTful API Design

// Example: Our proposal generation endpoint
POST /api/proposal/generate
{
  "problemText": "My Tuesdays are too hectic",
  "clarifications": ["I need time for deep work", "Can't miss office hours"],
  "events": [...calendar_events],
  "preferences": {
    "sleepTargetHours": 8,
    "priorities": ["sleep", "focus"]
  }
}

We built 12+ API endpoints with comprehensive validation, error handling, and type safety using Zod schemas. Every request and response is validated, ensuring robust data flow throughout the system.

2. OAuth & Authentication

// Secure calendar access with NextAuth.js
const session = await getServerSession(authOptions);
const calendarClient = new GoogleCalendarClient(session.accessToken);

We implemented enterprise-grade authentication using NextAuth.js, enabling secure Google Calendar integration while protecting user privacy and data.

3. AI Integration

Our Gemini AI doesn't just move events around—it understands context:

const proposal = await geminiClient.generateProposal({
  problemText: "Optimize my week for productivity",
  clarifications: userResponses,
  events: calendarEvents,
  preferences: userGoals
});

The AI considers:

Temporal constraints (deadlines, fixed events)
Personal preferences (sleep patterns, focus times)
Contextual awareness (exam periods, project deadlines)
Optimization goals (productivity, balance, stress reduction)

4. Real-time Data Processing

// Live calendar synchronization
const events = await calendarClient.listEvents({
  timeMin: startOfWeek,
  timeMax: endOfWeek,
  singleEvents: true
});

// Conflict detection and resolution
const conflicts = findTimeConflicts(proposedChanges, existingEvents);

We built real-time processing for:

Live calendar synchronization with Google Calendar API
Dynamic conflict detection and resolution
Streaming TTS responses using ElevenLabs for conversational interaction

The User Experience Flow

Natural Language Input: Users describe their scheduling problem in plain English
Intelligent Clarification: AI asks targeted questions to understand constraints and goals
Proposal Generation: AI analyzes the calendar and generates optimized alternatives
Visual Comparison: Side-by-side "before vs. after" calendar views
Approval & Refinement: Users can approve, modify, or reject proposals
Automatic Application: Approved changes sync directly to Google Calendar

Challenges We Ran Into

The AI Context Problem

Challenge: Getting Gemini to understand the nuance of scheduling decisions—not just moving events, but optimizing for life balance.

Solution: We built a multi-layered prompting system that provides rich context about user goals, preferences, and constraints. The AI now considers factors like sleep quality, focus windows, and stress reduction alongside basic scheduling logic.

Binary Response Handling

Challenge: The infamous "Response body object should not be disturbed or locked" error when handling TTS audio streams.

Solution: We implemented proper response cloning and binary-safe error handling:

// Before: This caused the error
if (!res.ok) {
  console.error(await res.text()); // Tries to read binary as text
}

// After: Safe binary handling
if (!res.ok) {
  try {
    const errorData = await res.clone().json();
    errorMessage = errorData.message;
  } catch {
    errorMessage = `HTTP ${res.status}`;
  }
}

Real-time Calendar Integration

Challenge: Maintaining data consistency while allowing users to modify their Google Calendar externally.

Solution: We built conflict detection algorithms that identify scheduling conflicts and provide intelligent resolution suggestions, ensuring users never lose important events or create double-bookings.

Conversation Flow Design

Challenge: Creating a natural back-and-forth dialogue that feels helpful, not intrusive.

Solution: We implemented a stateless heuristic system that determines when to ask clarifying questions vs. when to generate proposals, based on the complexity of the request and available context.

Accomplishments We're Proud Of

Full-Stack AI Integration: Successfully integrated Gemini AI, ElevenLabs TTS, and Google Calendar API into a cohesive system
Enterprise-Grade Architecture: Built 12+ API endpoints with comprehensive validation, error handling, and type safety
Real-time Processing: Achieved seamless live calendar synchronization with conflict detection
Conversational UX: Created natural language interface that feels intuitive and helpful
Production-Ready Code: Implemented proper authentication, security, and error handling throughout
Testing Infrastructure: Built comprehensive test suite with unit, integration, and contract tests
Performance Optimization: Resolved complex binary response handling and memory management issues

What We Learned

Building Clarity taught us that scheduling isn't just about time management—it's about life design. We discovered:

Technical Insights

AI Context Awareness: Getting AI to understand not just what events exist, but why they matter and how they should be prioritized
Constraint Satisfaction: Building algorithms that respect hard constraints while optimizing for soft preferences
Real-time Integration: Seamlessly syncing with external APIs while maintaining data integrity

Human-Centered Insights

Control vs. Automation: Users want AI assistance, but they need to maintain agency over their time
Visual Communication: The "before vs. after" comparison is essential for building trust in AI decisions
Conversational Interface: Natural language is how humans naturally think about scheduling problems

System Design Lessons

Error Handling: Proper binary response handling and response cloning are crucial for robust applications
Authentication Flow: OAuth integration requires careful attention to token management and security
API Design: Type-safe endpoints with comprehensive validation prevent runtime errors and improve developer experience

What's Next for Clarity

Short-term Goals

Mobile App: Native iOS and Android apps for on-the-go scheduling
Smart Notifications: Proactive suggestions based on calendar patterns and user behavior
Team Scheduling: Multi-user optimization for group meetings and shared calendars

Medium-term Vision

Predictive Scheduling: AI that learns your preferences and suggests optimal times for new events
Wellness Integration: Integration with fitness trackers and sleep data for health-aware scheduling
Context Awareness: Location-based scheduling that considers travel time and commute patterns

Long-term Impact

Academic Focus: Specialized features for students including exam scheduling and study time optimization
University Integration: Features to integrate with university calendars and dining hall/other facility schedules
Research Platform: Open-source components to advance AI-driven scheduling research

The math is simple but powerful: $$\text{Time Saved} = \text{Hours per week manually rescheduling} \times \text{Weeks per year} \times \text{Users}$$

For a typical student managing 20+ events per week, that's 5-10 hours per week reclaimed—time that can be spent on what truly matters: learning, creating, and living.

We didn't just build an app—we built a new relationship with time itself.