Platform Architecture

Operanix is built as a 7-layer Agent Operating System designed to manage the full lifecycle of enterprise AI agents — from knowledge ingestion to production deployment with continuous governance.

System Overview

The Operanix Agent OS organizes all platform capabilities into seven distinct layers, each with a clear responsibility boundary. Higher layers depend on lower layers but never the reverse, ensuring clean separation of concerns and independent scalability.

Agent Orchestration

The orchestration engine is the core runtime that manages request routing, agent lifecycle, and multi-agent collaboration.

Agent Roster

Operanix ships with 11 pre-configured agents, each specializing in a distinct business domain:

Routing & Dispatch

When a request arrives, the orchestrator follows this flow:

1. Intent classification — Classify the request to determine the target agent using keyword and embedding-based matching.
2. Agent selection — Check the target agent's deployment status, trust score, and rate limits. Fall back to a general agent if the primary is unavailable.
3. Context assembly — Pull relevant knowledge from the RAG pipeline, inject tenant-scoped system prompts, and attach conversation history.
4. Execution — Send the assembled prompt to the configured LLM provider (Gemini, GPT-4, Claude) with tool bindings.
5. Governance check — Evaluate the response against compliance rules, content policies, and citation requirements before returning.
6. Response delivery — Stream the approved response back to the client with metadata (citations, confidence, cost tracking).

Multi-Agent Collaboration

For complex requests spanning multiple domains, the orchestrator can initiate a collaboration session where multiple agents contribute in sequence or parallel. A designated lead agent synthesizes the final response and is accountable for governance compliance.

Knowledge Pipeline

Operanix implements a two-layer RAG architecture that combines structured entity knowledge with document chunk retrieval for high-precision, citation-backed responses.

Layer 1: Structured Entities

Business entities (products, policies, people, processes) are stored as structured records with typed fields, relationships, and metadata. This layer enables deterministic, fact-based answers with exact citations.

Layer 2: Document Chunks

Unstructured documents (PDFs, web pages, spreadsheets) are chunked, embedded, and stored in vector storage. Semantic search retrieves relevant chunks at query time and merges them with structured entity results.

Pipeline Stages

The knowledge pipeline processes content through six stages:

1. Sources — Ingest from web crawls, file uploads, API connectors, and manual entry. Supports 40+ file formats.
2. Review — Content goes through quality checks, deduplication, and optional human review before processing.
3. Train — Documents are chunked, entities are extracted, embeddings are generated, and relationships are mapped.
4. Evaluate — Automated evaluation scores knowledge quality across relevance, accuracy, freshness, and coverage dimensions.
5. Intelligence — Processed knowledge is indexed and made available to the agent runtime for retrieval.
6. Publish — Versioned knowledge snapshots are published, with rollback capability and change tracking.

Tenant Intelligence Pipeline

Each tenant runs a 12-stage intelligence pipeline on a configurable schedule:

1. Source discovery and crawl scheduling
2. Content extraction and normalization
3. Entity recognition and classification
4. Relationship mapping and graph construction
5. Embedding generation (multi-model)
6. Quality scoring and validation
7. Deduplication and conflict resolution
8. Knowledge graph merge and versioning
9. Agent knowledge binding updates
10. Evaluation suite execution
11. Trust score recalculation
12. Publication and cache invalidation

Trust & Governance Engine

Every agent action is scored in real time across five dimensions that combine into a composite Trust Score. This score determines whether an action can proceed automatically, requires human approval, or is blocked.

Trust Score Formula

Trust Score = (Agent Quality    × 0.30)
            + (Citation Score   × 0.20)
            + (Compliance Score × 0.20)
            + (Governance Score × 0.15)
            + (Knowledge Score  × 0.15)

Action Thresholds

Multi-Tenant Architecture

Operanix enforces strict tenant isolation at every layer of the stack using Firestore's document-level security model.

Data Isolation

• Tenant-scoped collections — All data is stored under tenants/{tenantId}/ paths. Cross-tenant reads are impossible by design.
• Security rules — Firestore rules enforce that authenticated users can only access documents within their tenant scope.
• Embedding isolation — Vector indexes are partitioned by tenant ID, preventing knowledge bleed across organizations.
• API key scoping — Each API key is bound to a single tenant and cannot be used to access other tenants' data.

Tenant Configuration

Each tenant has an independent configuration document controlling:

• Active agents and their deployment status
• LLM provider preferences and API key bindings
• Knowledge pipeline schedules and source lists
• Governance thresholds and approval workflows
• Branding and white-label settings
• Usage quotas and rate limits

Event System

Operanix produces a comprehensive event stream that powers audit logging, observability, and webhook integrations.

Pipeline Events

Every knowledge pipeline run emits events at each stage transition, enabling real-time monitoring and alerting:

• pipeline.started / pipeline.completed / pipeline.failed
• stage.entered / stage.completed with duration and item counts
• source.crawled / source.error with status codes and retry metadata
• entity.created / entity.updated / entity.merged

Audit Logging

All agent actions, governance decisions, and administrative changes are logged with:

• Timestamp, actor (user or system), tenant ID
• Action type and target resource
• Before/after state diffs for mutations
• Trust score at time of decision
• Approval chain (if applicable)

Audit logs are immutable and retained for the period defined by the tenant's compliance policy (default: 7 years).

Deployment Architecture

Frontend

The Operanix portal is a Next.js application deployed on Firebase Hosting with CDN edge caching. Static assets are served from Google's global edge network for sub-100ms load times worldwide.

Backend

API and business logic run on Cloud Functions (Gen 2) with automatic scaling from zero to thousands of concurrent instances. Heavy workloads (knowledge pipeline batch processing, evaluation suites) run on Cloud Run for higher memory and timeout limits.

Scheduled Pipelines

Cloud Scheduler triggers tenant intelligence pipelines on configurable cron schedules. Each pipeline run is an independent Cloud Function invocation with its own timeout and retry policy.

Secrets & Configuration

Tenant API keys, LLM provider credentials, and integration tokens are stored in Google Secret Manager with IAM-scoped access. Application configuration uses Firebase Remote Config for feature flags and runtime tuning.

API Architecture

Express Routes

The API is built on Express.js with a modular router architecture. Each of the 14 endpoint groups is an independent router module mounted on the main app:

app.use('/api/auth',        authRouter);
app.use('/api/chat',        chatRouter);
app.use('/api/agents',      agentRouter);
app.use('/api/collaborate',  collaborationRouter);
app.use('/api/governance',  governanceRouter);
app.use('/api/knowledge',   knowledgeRouter);
// ... 8 more routers

Middleware Stack

Every request passes through a layered middleware stack:

1. CORS — Configured per-tenant with allowed origins
2. Rate limiting — Token-bucket algorithm with per-tenant and per-endpoint limits
3. Authentication — Firebase Auth ID token verification or API key validation
4. Tenant resolution — Extract and validate tenant ID from token claims
5. Authorization — RBAC check against the user's role and the requested resource
6. Request validation — Zod schema validation for request body, query params, and path params
7. Audit logging — Record the request metadata for the audit trail

Authentication

The API supports two authentication methods:

• Firebase ID tokens — For portal users, obtained via Firebase Auth sign-in flow
• API keys — For server-to-server integrations, scoped to a tenant with configurable permissions

Both methods resolve to a tenant context that scopes all subsequent database queries and operations.