SynthiCal AI

Author: Technical Documentation Team
Date: April 15, 2026
Version: 2.0
Status: Current
Last Updated: April 15, 2026

Document Overview

This document provides a comprehensive technical specification for SynthiCal AI, an AI-powered event extraction platform that transforms unstructured inputs into calendar-ready events. It follows industry best practices for software architecture documentation, presenting information at multiple abstraction levels to serve different stakeholder needs.

Target Audience: Software Engineers, System Architects, DevOps Engineers, Technical Lead, QA Engineers

Document Scope: Complete system architecture, implementation details, deployment strategy, and maintenance procedures

Table of Contents

1. Executive Summary
2. System Context
3. Container Architecture
4. Component Design
5. Data Flow Architecture
6. Service Layer Design
7. Infrastructure & Deployment
8. Security Architecture
9. Performance & Scalability
10. Quality Assurance
11. Future Roadmap

1. Executive Summary

1.1. Business Problem

Professionals, students, and event organizers face a universal challenge:

• Fragmentation: Event information arrives via text, email, web pages, documents, images, and voice — never in a calendar-ready format
• Manual Entry: Copying dates, times, locations, and descriptions into calendar apps is tedious and error-prone
• Format Diversity: Dates appear as "next Friday," "03/15," "March 15th at 2pm EST," or embedded in paragraphs — requiring human interpretation
• Multi-Source Volume: Conference schedules, meeting invitations, and itineraries often contain multiple events that must each be entered individually

1.2. Solution Overview

SynthiCal AI automates the entire extraction-to-calendar pipeline:

Core Value Proposition:

• Multimodal Input: Accept text, URLs, documents, images, and audio recordings
• AI-Powered Extraction: Google Gemini 3.1 Pro identifies and structures event data from any format
• Timezone Intelligence: Context-aware resolution of relative dates against the user's local time
• Universal Export: One-click export to Google Calendar, Apple Calendar, Outlook, or .ics files

Technical Innovation:

• Tiered URL processing (JSON-LD structured data → AI fallback)
• Gemini Files API integration for multimodal document/image/audio analysis
• Server-side AI processing with zero client-side API key exposure
• Privacy-first architecture with no user data persistence

1.3. Technology Stack Overview

2. System Context

2.1. System Context Diagram

This high-level view shows SynthiCal AI's position in the broader ecosystem:

2.2. Key System Characteristics

Simplicity: Single-page application with no authentication, routing, or persistent state
Privacy: Zero user data storage; uploaded files deleted immediately after processing
Performance: Tiered URL extraction delivers structured-data results in under 1 second
Accessibility: Serverless architecture with global CDN for worldwide access
Cost Efficiency: Pay-per-use serverless model; no idle infrastructure costs

2.3. System Boundaries

Included in System:

• Web application frontend (React SPA)
• API backend (Firebase Cloud Function with Express)
• AI extraction pipeline (text, URL, file)
• ICS calendar file generation
• Cross-platform calendar export UI

External Dependencies:

• Google Gemini API for AI processing
• Target web pages for URL extraction
• Firebase for infrastructure and secrets
• Calendar platforms for event import

3. Container Architecture

3.1. Container Diagram

This shows the high-level technology choices and how containers communicate:

3.2. Technology Decisions

3.3. Communication Protocols

Frontend ↔ Firebase Hosting: HTTPS with CDN edge caching for static assets
Frontend ↔ Cloud Function: HTTPS REST API with JSON payloads (text, URL) and multipart form data (files)
Cloud Function ↔ Gemini SDK: HTTPS via @google/generative-ai SDK
Cloud Function ↔ Gemini Files API: HTTPS REST with resumable upload protocol
Cloud Function ↔ Web Pages: HTTPS fetch with desktop Chrome User-Agent
Frontend ↔ Calendar Platforms: Client-side atcb_action generates platform-specific URLs/downloads

4. Component Design

4.1. Frontend Component Architecture

This diagram shows the React component hierarchy and relationships:

4.2. Component Responsibilities

4.3. State Management Architecture

5. Data Flow Architecture

5.1. Event Extraction Flow

This diagram shows the complete data flow from user input to calendar export:

5.2. URL Processing Pipeline

The URL processor implements a sophisticated tiered extraction strategy:

5.3. File Processing Pipeline

The multimodal file processor manages the complete lifecycle from upload to cleanup:

5.4. Event Data Schema

All extraction paths produce events conforming to this schema:

6. Service Layer Design

6.1. Service Architecture Overview

6.2. Text Processing Service (utils/gemini.js)

Core Implementation: Uses the @google/generative-ai SDK with gemini-3.1-pro-preview.

Prompt Engineering:

Header: Expert event extraction assistant role + JSON schema specification
Browse Hint: URL context if available (instructs model to prefer live content / JSON-LD)
Time Context: Current UTC time + user timezone + formatted local time
Content: User's text input

Key Features:

• responseMimeType: "application/json": Forces Gemini to return valid JSON
• Fallback JSON Parsing: If JSON.parse fails, regex extracts the first {...} block from the response
• normalizeEvents(): Handles four possible response shapes — array, {events: [...]}, {event: {...}}, or bare object

6.3. File Processing Service (processors/file.js)

Gemini Files API Integration (REST, not SDK):

Supported MIME Types (via Gemini's multimodal capabilities):

• Documents: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain, text/rtf
• Images: image/png, image/jpeg, image/webp, image/heif
• Audio: audio/webm, audio/mp4

6.4. URL Processing Service (processors/url.js)

Tiered Extraction Strategy:

JSON-LD Normalization (normalizeFromJsonLd):

• Maps name / title → title
• Converts startDate / endDate to ISO via Date constructor
• Extracts location from string, location.name, location.address, or location.url
• Sets original_link to the source page URL
• Defaults: start_datetime = now, end_datetime = now + 1 hour

6.5. ICS Generation Service (utils/ics-generator.js)

RFC 5545 Compliance:

• Uses the ics library's createEvents function
• Converts all datetimes to UTC components: [year, month, day, hour, minute]
• Formats descriptions by converting [br] markers to newlines
• Includes url field from original_link when available
• Returns text/calendar MIME type with Content-Disposition: attachment

6.6. Error Handling Strategy

7. Infrastructure & Deployment

7.1. Firebase Platform Architecture

7.2. Deployment Configuration

Firebase Hosting (firebase.json):

{
  "hosting": {
    "public": "frontend/dist",
    "rewrites": [
      { "source": "/api/**", "function": "api" },
      { "source": "**", "destination": "/index.html" }
    ]
  },
  "functions": [
    { "source": "functions", "codebase": "default" }
  ]
}

Vite Development Proxy (vite.config.js):

server: {
  port: 3000,
  proxy: {
    '/api': {
      target: 'http://127.0.0.1:5001/synthicalai/us-central1/api',
      changeOrigin: true
    }
  }
}

Deployment Commands:

• cd frontend && npm run build — Build frontend to frontend/dist
• firebase deploy — Deploy hosting + functions
• firebase deploy --only hosting — Frontend only
• firebase deploy --only functions — Backend only

7.3. Performance Characteristics

8. Security Architecture

8.1. Security Measures Implemented

8.2. Data Privacy Compliance

Current Privacy Posture:

• No personal information collected
• No user accounts or authentication
• No server-side data persistence
• No tracking cookies (GA4 is opt-in via env variable)
• All AI-processed files deleted after extraction
• Public SEC-style transparency notice in footer about Gemini data handling

8.3. Recommended Security Enhancements

8.3.1. Immediate Actions

Rate Limiting:

// Add per-IP rate limiting to prevent abuse
const rateLimit = require('express-rate-limit');
app.use('/api', rateLimit({ windowMs: 60 * 1000, max: 20 }));

Content Security Policy:

response.set('Content-Security-Policy',
  "default-src 'self'; " +
  "script-src 'self' https://www.googletagmanager.com; " +
  "connect-src 'self' https://www.google-analytics.com"
);

8.3.2. Medium-term Improvements

• Server-side file size validation (currently only client-side 25 MB check)
• MIME type allowlist on the backend to reject unsupported file types
• Request origin validation for tighter CORS policy
• Security headers: X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security

9. Performance & Scalability

9.1. Frontend Performance

Bundle Optimization:

• Vite 7: Tree shaking, code splitting, and minification
• Tailwind CSS 4: Only utility classes used in source are included in production build
• No Router: Single-page architecture eliminates route-based code splitting overhead (not needed for focused scope)

Runtime Performance:

• useMemo: acceptByTab map memoized to avoid re-creation on every render
• Controlled Components: Minimal state updates via useState hooks
• Set-based Selection: O(1) toggle/check for event multi-select

9.2. Backend Performance

Serverless Scaling:

• Firebase Functions (Gen 2) auto-scale from 0 to thousands of concurrent instances
• No cold start penalty for warm instances
• Stateless design allows unlimited horizontal scaling

API Efficiency:

• JSON-LD extraction avoids Gemini API calls entirely for well-marked pages
• responseMimeType: "application/json" reduces post-processing overhead
• Busboy streams file data instead of buffering entire multipart request

9.3. Scalability Architecture

10. Quality Assurance

10.1. Current Testing Approach

Manual Testing:

• Input type coverage: text, URL (with and without JSON-LD), PDF, images, audio
• Timezone variations: UTC, US Eastern, US Pacific, IST, JST
• Edge cases: empty inputs, malformed URLs, oversized files, no events found
• Calendar export: Google Calendar, Apple Calendar, Outlook.com, .ics download

10.2. Recommended Testing Enhancements

Unit Testing Framework: Vitest (aligned with Vite ecosystem)

Test Coverage Areas:

• normalizeEvents() — all four input shapes
• normalizeFromJsonLd() — string locations, object locations, missing fields
• toParts() — valid ISO strings, invalid strings, null input
• formatDate() — various ISO formats, edge cases
• generateICS() — single event, multiple events, missing fields

Integration Testing:

• Mock Gemini API responses for deterministic extraction testing
• Mock JSDOM for URL processing pipeline testing
• End-to-end API tests via Firebase Emulator

10.3. Code Quality Standards

Current Practices:

• ES Modules throughout ("type": "module" in all package.json files)
• Consistent async/await patterns with try/catch error handling
• Clear separation of concerns: routes, processors, utilities
• Central Express error middleware for uniform error responses

Recommended Improvements:

• TypeScript migration for type safety
• ESLint configuration with React and Node.js rule sets
• Prettier for consistent code formatting
• Pre-commit hooks for automated quality checks

11. Future Roadmap

11.1. Immediate Priorities (Next 2-4 weeks)

11.1.1. Security (Critical)

• Rate Limiting: Add per-IP rate limits to prevent API abuse
• Server-Side File Validation: Enforce file size and MIME type limits on the backend
• Security Headers: Add CSP, HSTS, X-Frame-Options, X-Content-Type-Options

11.1.2. Reliability (High)

• Retry Logic: Add exponential backoff for Gemini API calls in text and URL paths
• Timeout Handling: Set explicit timeouts on all external HTTP requests
• Error Boundaries: Add React error boundaries for component-level failure isolation

11.1.3. User Experience (High)

• Event Editing: Allow users to edit extracted event details before export
• Timezone in Calendar Export: Use user-selected timezone in atcb_action instead of browser default
• Loading Progress: Show extraction stage indicators (uploading → analyzing → extracting)

11.2. Medium-term Goals (1-3 months)

11.2.1. Feature Enhancements

• Chrome Extension: One-click extraction from any web page
• Email Integration: Connect email accounts for automatic event extraction from inbox
• Recurring Events: Pattern detection for "every Tuesday" or "weekly meeting" descriptions
• Batch Documents: Process multi-page PDFs with per-page or per-section event extraction
• Direct Calendar API: Google Calendar OAuth integration for one-tap event creation

11.2.2. Technical Improvements

• TypeScript Migration: Full TypeScript conversion for frontend and backend
• React Router: Add routing for shareable extraction results
• User Accounts: Optional Firebase Auth for extraction history and saved preferences
• WebSocket Progress: Real-time extraction progress updates for file processing

11.3. Long-term Vision (6-12 months)

11.3.1. Platform Expansion

• Mobile Applications: Native iOS and Android apps with camera and microphone integration
• API Platform: Public REST API for third-party integrations
• Team Collaboration: Shared extraction results with team calendar integration
• Zapier/Make Integration: Connect SynthiCal AI to workflow automation platforms

11.3.2. AI Enhancements

• Smart Deduplication: Detect and merge duplicate events from multiple sources
• Context Learning: Improve extraction accuracy based on correction patterns
• Multi-Language Support: Event extraction from non-English sources
• Calendar Conflict Detection: Warn about scheduling conflicts with existing events

12. Conclusion

SynthiCal AI demonstrates how focused architecture and modern AI capabilities can solve a universal productivity pain point. The application successfully combines:

• Multimodal Intelligence: A single AI model (Gemini 3.1 Pro) handles text, documents, images, and audio through a unified extraction pipeline
• Tiered Processing: URL extraction prioritizes structured data over AI processing, optimizing for both speed and cost
• Privacy-First Design: No accounts, no storage, no tracking — uploaded files are deleted immediately after processing
• Universal Export: Cross-platform calendar integration via add-to-calendar-button and RFC 5545-compliant ICS generation

The serverless architecture on Firebase provides infinite scalability with zero idle costs, while the focused single-page design keeps the user experience simple and fast. The clear separation between the Express API layer and processing services creates a maintainable foundation for future enhancements like Chrome extension support, email integration, and direct calendar API connections.