Operiq AI Technical Documentation

Working professionals across industries spend a significant portion of their day on repetitive, time-consuming tasks: drafting emails, summarizing meetings, planning tasks, and researching topics. These activities, while necessary, divert attention from high-value strategic work and creative problem-solving.

Studies show that knowledge workers can spend up to 60% of their time on administrative and communication tasks rather than core responsibilities. The cumulative effect is reduced productivity, delayed decision-making, and professional burnout.

The Solution

Operiq AI is an AI-driven workplace productivity platform designed to automate and accelerate these repetitive tasks. By leveraging large language models and intelligent automation, Operiq AI helps professionals reclaim their time and focus on what matters most.

Operiq AI delivers five core AI-powered productivity tools, each designed to address a specific workplace pain point. All tools share a unified interface philosophy: single-column composer canvas, intelligent AI generation, and a copy-and-refine workflow.

Overview

Operiq AI is deployed on Netlify's global edge infrastructure, combining server-side rendering with a real-time backend powered by Convex. The frontend is a single-page application built with TanStack Start and React 19, optimized for instant navigation and offline resilience.

Infrastructure Components

• Netlify Edge — Global CDN with edge functions for request routing, authentication middleware, security headers, and geolocation-aware responses.
• Convex Cloud — Real-time reactive backend providing ACID-compliant database operations, scheduled functions, file storage, and built-in authentication.
• AI Providers — OpenAI-compatible API (via OpenRouter) with NVIDIA-hosted models (Mistral Large 3, Llama 3.3, Nemotron); ElevenLabs for TTS/STT; Hugging Face for image/video generation.
• External Services — Resend for transactional email delivery; Stripe for subscription billing (ZAR currency) and payment processing.

Deployment Topology

The application deploys as a single Netlify site with SSR via a manual server function wrapper. Preview deployments are generated on every pull request. The Convex backend runs in a separate deployment with environment-specific configuration managed through deploy contexts and environment variables.

NETLIFY EDGE
  +-- CDN Cache
  +-- Edge Functions (security headers)
  +-- Static Assets
  |
  +-> SSR Server (TanStack Start)
        +-> API Routes (/api/chat, /api/huggingface, etc.)
        |
        +-> CONVEX (Database + Auth)
        +-> AI_PROVIDER (OpenAI-compatible API)
        +-> RESEND (Email)
        +-> ELEVENLABS (Voice)
        +-> HUGGINGFACE (Image/Video)

Architecture Diagrams

System Architecture Overview

The architecture diagram above illustrates the full system topology including frontend, SSR layer, API gateway, Convex backend, and external AI service integrations.

Frontend Architecture

The frontend is built with React 19, TanStack Start (for SSR),TanStack Router (file-system routing), Tailwind CSS v4, andshadcn/ui components. Each route is a self-contained module with its own head metadata, loading states, and error boundaries.

Component Hierarchy

RootLayout (__root.tsx)
  +-- ConvexAuthProvider
        +-- DevToolsGuard
              +-- AuthGate
                    +-- AppShell
                    |     +-- Sidebar
                    |     |     +-- NavItem (Assistant, Code)
                    |     |     +-- Studio NavItem (Email, Meetings, Planner, Research)
                    |     |     +-- UserProfile + LogoutButton
                    |     +-- Main Content
                    |           +-- Feature Pages
                    |           |     +-- Email Studio
                    |           |     +-- Meeting Intelligence
                    |           |     +-- Task Planner
                    |           |     +-- Research Hub
                    |           |     +-- Operiq Code
                    |           +-- AI Assistant
                    |           +-- Settings (General, Personalization, Billing, Storage, Contact)
                    +-- Public Routes
                          +-- /login
                          +-- /signup
                          +-- /invite/:token
                          +-- /docs

Backend Architecture

The backend is organized into Convex modules, each handling a specific domain. Actions provide the bridge between Convex's deterministic functions and external APIs (AI providers, email services). Internal mutations and queries handle state management with reactive updates to connected clients.

convex/
  +-- schema.ts              # Database schema (users, profiles, threads, emailDrafts,
  |                         # meetingSummaries, taskPlans, researchAnalyses, sharedChats, billing)
  +-- auth.ts                # Convex Auth configuration (Password provider)
  +-- users.ts               # User management (me, updateProfile)
  +-- profiles.ts            # Profile CRUD (getProfile, updateProfile, updateAvatar)
  +-- emailDrafts.ts         # Email draft generation and storage
  +-- summaries.ts           # Meeting summary generation
  +-- plans.ts               # Task plan generation
  +-- analyses.ts            # Research analysis generation
  +-- billing.ts             # Usage tracking, plan management, subscriptions
  +-- ai.ts                  # Shared AI helper (callAI via fetch)
  +-- http.ts                # HTTP endpoint handlers
  +-- _generated/
        +-- api.ts           # Auto-generated API types

src/routes/api/
  +-- chat.ts                # Streaming chat endpoint (normal + agent mode)
  +-- code.ts                # Code generation endpoint
  +-- elevenlabs-tts.ts      # Text-to-speech streaming
  +-- elevenlabs-stt.ts      # Speech-to-text
  +-- huggingface.ts         # Image generation
  +-- huggingface-video.ts   # Video generation
  +-- resend.ts              # Email sending

Database Schema

The Convex database schema includes the following tables (real project schema):

profiles          — userId, displayName, avatarUrl, createdAt
threads           — userId, title, messages[{id, role, content, createdAt}], createdAt, updatedAt
emailDrafts       — userId, recipient, subject, tone, audience, context, draft, sent, sentAt, createdAt
meetingSummaries  — userId, meetingType, notes, output, createdAt
taskPlans         — userId, horizon, tasks, goals, output, createdAt
researchAnalyses  — userId, material, question, depth, output, createdAt
sharedChats       — threadId, ownerId, token, isActive, createdAt, invitedUserIds[]
billing           — userId, plan, aiRequestsUsed, aiRequestsLimit, imagesGenerated,
                    imagesLimit, storageUsed, storageLimit, subscriptionStatus,
                    currentPeriodStart, currentPeriodEnd, createdAt

State Management

• Server State — Managed by Convex's reactive queries (useQuery). Data changes automatically propagate to all connected clients without manual cache invalidation.
• Client State — Local component state via React'suseState for ephemeral UI state (form inputs, loading indicators, model selection).
• Auth State — Managed via @convex-dev/auth with ConvexAuthProvider at the root level. SSR-safe wrapper (useSsrConvexAuth) prevents server-side crashes.
• Local Storage — Theme preference (operiq-theme), model selection (operiq-chat-model, operiq-code-model), agent mode (operiq-agent-mode), and user preferences (language, voice, custom instructions).

Prompt engineering is a core competency, representing 25% of the evaluation criteria. Operiq AI demonstrates structured, tested, and refined prompts across all AI features.

Prompt Structure

Every prompt in Operiq AI follows a consistent four-part structure:

• System Instructions — Define the AI's persona, role, and behavioral constraints.
• Context Injection — User-provided data (notes, topics, material) is injected with clear delineation from system instructions.
• Output Formatting — Explicit structure requirements (markdown sections, bullet lists, numbered items) ensure consistent, parseable output.
• Guardrails — Constraints on tone, length, prohibited content, and bias awareness to ensure responsible output.

1. Assistant System Prompt

The chat assistant uses a carefully crafted system prompt that defines its personality and boundaries:

You are Operiq AI, a calm, precise executive productivity assistant
for working professionals.

Specialties: drafting communications, summarizing meetings, structuring
plans, distilling research, and answering workplace questions.

Be concise, professional, and well-structured. Prefer markdown with
short headings and lists.

When uncertain, say so. Remind users to review AI-generated output
before acting on it when stakes are high.

Avoid speculation about real people and avoid politically loaded
claims; flag potential bias and limitations when relevant.

2. Agent Mode Extension

When agent mode is enabled, the system prompt is extended with ReAct (Reasoning + Acting) instructions:

You are Operiq AI, an autonomous agent with access to tools.
Follow this ReAct pattern:

1. THINK about what you need to do to answer the user's request.
2. If you need to fetch data or search, use the appropriate tool.
3. Observe the tool result and decide if you need more information.
4. Once you have enough information, provide a clear, helpful final answer.

Guidelines:
- Use web_search to find current information from the internet.
- Use fetch_url to retrieve content from specific web pages.
- If a tool returns insufficient results, try a different approach.
- Be concise and direct in your final answer.
- When you have enough information to answer, respond directly
  without calling more tools.

3. Email Generator Prompt

The email generator uses a dynamic prompt that adapts to user-selected parameters:

System:
You are an executive communications writer for Operiq AI.
Draft a polished business email.

Constraints:
- Tone: {formal|informal|persuasive}
- Audience: {client|manager|team}
- Recipient: {user-provided} (if any)
- Subject line hint: {user-provided} (if any)
- Include a clear subject line on the first line as "Subject: ..."
- If a recipient was provided, address them appropriately
- Concise, professional, no filler. Avoid emoji.
- Use markdown.

User Input:
Email purpose: {topic}
Additional context: {context}

4. Meeting Summarizer Prompt

System:
You analyze raw meeting notes/transcripts and produce a clear
executive briefing.

Meeting type: {1:1|team-sync|client-call|all-hands}

Return markdown with exactly these sections:
## Summary
A 3-5 sentence neutral synopsis.

## Key Decisions
Bulleted list of decisions made.

## Action Items
Bulleted list — each line: **Owner** — task — due date.

## Deadlines
Bulleted list of dates and what is due.

If a section has nothing, write "_None identified_".
Be thorough and accurate. Flag any ambiguous points.

User Input:
{raw meeting notes}

5. Task Planner Prompt

System:
You are an executive productivity coach. Build a prioritized
{daily|weekly} plan.

Return markdown with:
## Prioritized Plan
A numbered schedule with suggested time blocks.
Mark each item P1 / P2 / P3.

## Rationale
Briefly explain prioritization (Eisenhower / impact-effort lens).

## Productivity Suggestions
3 concrete improvements tailored to the workload.
Consider dependencies between tasks and energy levels.

User Input:
Tasks: {task list}
Goals/Context: {goals}

6. Research Analysis Prompt

System:
You are a senior research analyst. Distill the provided material.

Analysis depth: {quick|deep|executive}

Return markdown with:
## Executive Summary
3-5 sentences.

## Key Insights
Bulleted list of the most important findings.

## Recommendations
Numbered, actionable, written for decision-makers.

## Open Questions
Bulleted list of gaps or items needing verification.

Be objective. Flag potential biases in the source material.

User Input:
Material: {research material}
Focus question: {question}

Prompt Refinement Loop

When a user requests refinements, the previous output and the user's requested changes are sent back to the AI as a continuation. The model receives the full context of the original generation plus the refinement instructions, enabling iterative improvement without losing context. This refinement loop is available across all five studio tools.

Model Selection

Operiq AI uses a tiered model strategy with branded names mapped to actual provider models:

Responsible AI practices represent 10% of the evaluation criteria for the Operiq AI implements comprehensive safeguards across bias mitigation, data privacy, transparency, and ethical use.

Bias Mitigation Strategies

• Prompt-Level Bias Detection — System prompts explicitly instruct the AI to "flag potential biases in the source material" and "avoid politically loaded claims". The research assistant prompt includes a dedicated section for bias flagging.
• Balanced Output Structure — Meeting summaries and research analyses use neutral, fact-based markdown sections. Opinions are clearly labeled as such, and ambiguous points are flagged rather than resolved arbitrarily.
• Multi-Model Validation — Different model tiers (Ultra through Mini) allow users to cross-check outputs across model sizes, reducing single-model bias.

Data Privacy

• No Training on User Data — AI providers are configured to not use submitted data for model training. All API calls include privacy-preserving headers.
• Row-Level Security — Every Convex query and mutation enforces user ID checks. Users can only access their own data (email drafts, meeting summaries, etc.).
• Encryption — All data is encrypted in transit (TLS 1.3) and at rest (AES-256 via Convex). API keys are stored in environment variables, never in source code.
• Input Sanitization — All user inputs are validated with Zod schemas before being passed to AI providers or stored in the database.

Disclaimers and Validation

• AI Disclaimer — Every AI-generated output page includes a visible disclaimer: "This content was generated by AI. Please review and verify before using in professional contexts."
• Uncertainty Acknowledgment — The assistant prompt explicitly instructs the model to say when uncertain and to remind users to review high-stakes output.
• Output Validation — Zod schemas enforce input validation at the API boundary. Post-generation, output structure is validated against expected markdown sections.

Limitations Acknowledged

• Knowledge Cutoff — AI models have training knowledge cutoffs. The web search tool mitigates this but cannot guarantee real-time accuracy for all queries.
• Hallucination Risk — Like all LLMs, models may generate plausible but incorrect information. The system prompts explicitly guard against hallucinating facts.
• Context Window Limits — Very long inputs may be truncated. Users are advised to break large documents into smaller chunks.
• Not a Substitute for Professional Advice — Legal, medical, financial, and other specialized advice requires human expert review. Operiq AI is a productivity tool, not a professional advisor.

Ethical Safeguards

• Content Filtering — Input and output are filtered for harmful content. The system refuses requests that violate safety guidelines.
• Rate Limiting — Usage quotas prevent abuse and ensure fair access across all users (free tier: 20 AI requests/day, 5 images/day).
• Transparency — All AI-generated content is clearly labeled. Users always know when they are interacting with AI versus human-generated content.

Operiq AI is evaluated across six criteria. The table below maps each criterion to how Operiq AI addresses it.

Operiq AI integrates a diverse technology stack spanning AI services, development frameworks, and deployment infrastructure.

Below are three concrete examples of prompts and their corresponding outputs from Operiq AI, demonstrating the quality and structure of AI-generated content.

Example 1: Email Generation

Subject: Request for Project Deadline Extension

Dear [Manager's Name],

I am writing to request a two-day extension on the current project deadline,
which is currently scheduled for [original date].

During development, we encountered unexpected complexity in the API
integration phase that requires additional time to resolve properly.
Specifically, the third-party API documentation did not cover the
authentication edge cases we discovered during testing.

I have already outlined the remaining tasks and believe that with
two additional days, we can deliver a complete and thoroughly tested
solution by [new proposed date].

Please let me know if you would like to discuss this further or if
there is any additional information I can provide.

Best regards,
[Your Name]

Example 2: Meeting Summary

## Summary

The team reviewed Q3 performance metrics. Revenue grew 12% but customer
churn increased to 8%. The team decided to address onboarding as a
potential churn driver and approved hiring 2 new engineers before the
end of Q3.

## Key Decisions

- Address onboarding flow as a potential driver of the 8% churn rate
- Hire 2 new engineers by end of Q3

## Action Items

- **Sarah** — Prepare hiring plan — Due: Friday
- **John** — Review onboarding analytics — Due: Monday

## Deadlines

- Friday — Hiring plan due
- Monday — Onboarding analytics review due
- End of Q3 — 2 new engineers hired

## Next Meeting

Tuesday, 10:00 AM

Example 3: Research Analysis

## Executive Summary

AI-powered customer support is a viable investment for the organization.
Competitors using AI tools report 40% reduction in response times and
25% cost savings on support staffing. 68% of surveyed customers are
comfortable with AI-assisted support when human escalation is available.

## Key Insights

- Competitor A reduced average response time from 4 hours to 15 minutes
- Competitor B achieved 25% cost reduction in support operations
- 68% of customers accept AI support with human fallback
- 32% of customers still prefer direct human contact for complex issues

## Recommendations

1. Adopt a hybrid AI-human support model with AI handling L1 queries
2. Implement human escalation pathways for complex or sensitive issues
3. Pilot with a limited customer segment before full rollout
4. Invest in training the AI on company-specific product knowledge

## Open Questions

- What is the training data quality for our specific product domain?
- How will we measure customer satisfaction during the pilot?
- What is the total cost of ownership including integration and maintenance?

Throughout development, several technical and architectural challenges were encountered. The solutions implemented demonstrate practical problem-solving skills central to the programme.

Architecture Decisions

• Convex over Firebase — Chose Convex for its real-time reactive queries, ACID transactions, and built-in auth. Eliminates the need for separate WebSocket management.
• TanStack Start over Next.js — TanStack Start provides file-system routing with Vite-based builds, better TypeScript integration, and no vendor lock-in to a specific hosting provider.
• Serverless over Container — Netlify serverless functions with nft bundling provide zero-maintenance hosting with automatic scaling, eliminating DevOps overhead.
• OpenAI-Compatible API over Single Provider — Using the OpenAI-compatible API format (via OpenRouter) allows switching between Mistral, Meta, and NVIDIA models without code changes.
• Client-Side AI over Server-Only — All AI interactions go through server API routes that validate usage limits and sanitize inputs, keeping API keys secure while providing streaming responses to the client.