Architecture and runtime

The governed-agent fabric, in running code.

AEGIS runs as a multi-tenant vigilance platform with source evidence, human-gated action, auditable memory, tier-aware model policy, source-aware operational questions, and tenant-visible controls for proactive delivery and document vigilance.

Public architecture model

Five layers, two primitives.

This is the public model used across the Contract, README and enterprise pages. Evidence is not memory; proposals are not actions.

Interface/os, Standalone Omni, AEGIS Guardian, Telegram, WhatsApp, email, mobile, admin and public review surfaces.
OrchestrationIntent routing, operational ontology, agent dispatch, model policy, action ledger, approval routing, source grants and session state.
WorkersAgents, skills, Opportunity Radar, document-policy vigilance, source processors, scheduled loops and channel queues.
MemoryMemoria, accepted knowledge, Company Profile, provenance, trust labels and supersession trail.
EvidenceKB/Vault/Drive docs, CRM/HubSpot records, email, tasks, notes, calendar, provider links and audit rows.
Operational OntologyCanonical business intents and source-scoped record shapes for questions such as who needs follow-up or attention in native CRM or HubSpot.
GovernanceRBAC, source grants, skill grants, model policy, budget posture, audit trail and the human gate.
Live

/os, Omni, Standalone Omni, Guardian Windows pilot, Telegram commands, HubSpot read-through evidence, source-aware CRM follow-up/attention routing, Catch Ledger, Memoria, Radar, governed learning suggestions, signed in-system workflow/skill improvements, unified digest/proactive controls, document-vigilance status, selected model-policy routing, Proof Fabric / ADE v6, tenant isolation and audit.

Hardening

Guardian signing/update path, Chrome extension packaging, broader signed improvement appliers, broader model-policy metadata, M365 self-service, subject-level erasure verification and richer cost attribution.

Runtime stack

What runs AEGIS.

Lean web runtime, Postgres-first state, provider-swappable model gateway, and a native shell only where the browser cannot provide tray presence.

Backend

Python 3.12 · Flask · Gunicorn

Flask blueprints serve the SaaS app, APIs, public pages, Omni, integrations and admin surfaces. Gunicorn runs behind Nginx on the VPS.

Data

PostgreSQL 16 · pgvector

Per-tenant schemas hold business data; public tables hold platform state such as OAuth, Omni actions, Telegram jobs and audit logs. pgvector powers semantic search.

Model gateway

LiteLLM · model policy resolver

The app resolves allowed model aliases by tenant tier and intent before calls reach LiteLLM. Free/trial paths do not terminal-fall into premium spend.

Client surfaces

HTML · Vanilla JS · CSS

No SPA framework. The web surfaces are server-rendered and progressively enhanced: `/os`, desktop, mobile, Standalone Omni and public pages.

Desktop shell

Tauri v2 · Rust · WebView2

AEGIS Guardian wraps Standalone Omni for Windows tray presence, native notifications, quiet/resume, focused Decisions entry and start-on-login control.

Credential storage

Windows Credential Manager

Guardian stores only an attention-scoped device token in the OS vault. The shell does not cache tenant content or bypass approval gates.

Channels

Telegram · WhatsApp · Email · Teams path

Telegram has durable job processing and deterministic read commands. WhatsApp/email are live channels; Teams exists as the enterprise connector path.

Sources

Google Drive/Calendar · HubSpot · M365 path

Google OAuth covers Drive/Calendar; Gmail inbox uses IMAP. HubSpot read-through evidence and CRM follow-up/attention routing are live. M365 read paths are pilot/admin-configured pending self-service UX.

Proof tooling

ADE · Proof Fabric tools

Synthetic enterprise generator, verifier, capture helper and proof-bundle runner are built. ADE v6 is ratified for the fixed eight-category taxonomy: real IMAP + HubSpot CRM fusion, 8/8 strict across four clean runs, 0 false positives, 0 unresolved evidence, 0 ungated actions. Boundary: fixed-taxonomy proof, not arbitrary scenario detection.

Implementation map

Key code areas.

The codebase has grown; this is the map evaluators and contributors should use before reading individual files.

Core app
app/app.py, route blueprints, auth/RBAC, billing, settings and tenant bootstrap.
Omni / Guardian
app/omni_routes.py, app/omni_client_service.py, app/omni_action_ledger_service.py, guardian/src-tauri/*.
Vigilance loop
app/skill_runners/opportunity_radar.py, app/catch_ledger_service.py, app/catch_quality_verifier.py, app/catch_post_approval_action_service.py.
Intelligence substrate
app/operational_ontology.py, app/crm_source_registry.py, app/suggestion_builder.py, app/intelligence_events_service.py, app/intelligence_improvement_service.py, app/skill_performance_service.py. Skill-prompt changes are human-approved before they go live and verified against before/after rated runs; AEGIS-proposed changes additionally require signed apply through the Improvement Ledger. Broader workflow/routing/source/knowledge upgrades remain separately gated.
Documents
app/knowledge_service.py, app/document_policy_vigilance_service.py, app/document_policy_vigilance_scheduler.py.
Sources
app/source_registry.py, app/external_crm_evidence.py, app/hubspot_service.py, app/google_drive_service.py, app/m365_ingest_service.py.
Governance
app/model_policy_service.py, app/audit_service.py, app/agent_control_policy.py, app/rbac.py, app/guardian_service.py.
Proof Fabric
tools/ade/*, tools/generate_ade_enterprise.py, tools/capture_ade_actual_inputs.py, tools/run_ade_proof_bundle.py.

Need the deeper schematic?

The public stack keeps boundaries visible. Customer-specific control matrices, deployment diagrams and proof-run setup belong in a private review.

Evaluator Q&A Guardian downloads Book review