Valora
Valora

Valora Documentation

Technical architecture, core concepts, and implementation details for the Valora AI Workflow Command Center.

The Architecture of Focus

The modern knowledge worker's workflow is fractured. Traditional email clients are passive, simply displaying chronological lists of text. Conversely, modern AI assistants lack native context; forcing users to constantly copy-paste emails to get help.

Valora solves this by acting as an embedded Chief of Staff. By connecting directly to your Google Workspace via the Corsair SDK, Valora doesn't just read your email—it actively manages it. It classifies incoming emails, detects sensitive information, extracts calendar invites natively, and maintains a long-term vector memory of your preferences.

Core Systems

Autonomous AI Priority Engine

Every incoming email is parsed through Groq (LLaMA-3.3-70b-versatile). The AI analyzes sender, context, and tone to assign a Priority Score and label (Urgent, High, Normal, Low).

Persistent Agent Memory

Valora uses the Mem0 API combined with pgvector embeddings to give your AI agent permanent memory. It remembers your preferences and applies them to future interactions.

Calendar Intelligence

Scans threads for temporal context. With a single click, Valora extracts attendees, parses natural language times into ISO formats, and generates Google Calendar invites natively.

Data Sovereignty & Security

Tokens are AES-encrypted at rest. The 'Danger Zone' utilizes safe, atomic database transactions to sever foreign-key constraints and irreversibly wipe all local data when requested.

Technology Stack

Frontend
  • • Next.js 15 (App Router)
  • • React 19
  • • TailwindCSS
  • • Framer Motion
  • • Zustand State Management
Backend
  • • Node.js & tRPC
  • • Prisma ORM v6.19
  • • NextAuth (Auth.js v5)
  • • Corsair Google SDK
AI & Data
  • • Neon Serverless PostgreSQL
  • • pgvector Embeddings
  • • Groq API (LLaMA 3.3 70B)
  • • Mem0 Memory API

Architecture Deep Dive

[Google Workspace] │ (Webhooks) ▼ ┌──────────────┐ │ Corsair SDK │ └──────┬───────┘ │ (Raw Payload) ▼ ┌──────────────┐ (Context) ┌──────────────┐ │ Valora Core │ ◄──────────────────► │ Mem0 Vector │ │ (Next.js) │ │ Memory │ └──────┬───────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ Groq (LLaMA) │ (800+ tokens/sec Classification) └──────┬───────┘ │ ▼ ┌──────────────┐ │ Zustand UI │ (Sub-200ms Client Sync) └──────────────┘

1. Ingestion Layer: We use Corsair's headless Google API abstraction to ingest webhooks instantaneously. Unlike legacy polling systems, Valora knows about a new email the millisecond Google receives it.

2. Inference & Classification: Raw payloads are sanitized and sent to our Groq API endpoints. Using LLaMA-3.3-70b-versatile, the system achieves 800+ tokens/second inference to classify the urgency and intent of the email before it ever renders on the client.

3. Vector Storage: Processed emails and calendar events are converted into high-dimensional vector embeddings and stored in Neon PostgreSQL using the pgvector extension. This enables true semantic search (e.g., searching "when are we deploying" actually finds the email about "release scheduled for Friday").

4. Real-time Client Sync: The frontend bypasses traditional React render cycles for heavy lists by heavily leveraging Zustand and tRPC subscriptions, ensuring sub-200ms UI interactions.

Future Roadmap: The Unified Workspace

Google Drive Integration

Seamlessly attach, search, and semantically query all your Google Drive documents directly from the command center.

GitHub Repositories

Manage pull requests, issues, and CI/CD alerts without leaving your workflow. The AI will summarize diffs automatically.

Slack & Discord

Unified messaging. Let the AI triage your Slack DMs and prioritize them alongside your urgent emails.

WhatsApp Business

Bring client communications from WhatsApp into Valora. Have the AI draft professional responses based on your email history.

REST API Reference

GET
/api/gmail/messages
Fetch all synced emails for the authenticated user.
GET
/api/gmail/thread/:id
Retrieve a full email thread and its messages.
POST
/api/gmail/send
Send a new email or reply. Body requires { to, subject, text, threadId? }.
POST
/api/gmail/messages/:id/archive
Archive an email message.
POST
/api/gmail/messages/:id/read
Mark an email as read.
POST
/api/gmail/messages/:id/star
Toggle the starred state of an email.
POST
/api/search
Perform a semantic vector search across emails, calendar events, and memory using pgvector.
GET
/api/user/profile
Fetch the authenticated user's profile and plan details.
PATCH
/api/user/preferences
Update user preferences (theme, emailsPerPage, notifications).
POST
/api/speech-to-text
Upload an audio blob to transcribe speech via Groq Whisper API.
POST
/api/webhooks/gmail
Corsair webhook listener for real-time Gmail inbox changes.
POST
/api/webhooks/calendar
Corsair webhook listener for real-time Google Calendar updates.
GET
/api/trpc/:batch
Batched tRPC endpoint for type-safe client-server state sync.
POST
/api/search/corsair
Query the Corsair unified search index across all connected integrations.

Local Setup

terminal
git clone https://github.com/ashaafkhan/valora.git
cd valora
pnpm install
# Configure your .env file with API keys
pnpm dlx prisma generate
pnpm dlx prisma db push
pnpm run dev