Project Guide | AegisOps

AegisOps -- Multimodal Incident Review System

AegisOps turns raw incident logs and monitoring screenshots into structured, decision-ready incident reports -- complete with severity classification, root-cause analysis, timeline reconstruction, and operator handoff artifacts. Every analysis claim is backed by a deterministic replay eval suite before the live model path is trusted.

Three-Minute Proof

1. Open the Cloudflare demo or local UI and run one incident scenario.
2. Inspect the replay eval suite before trusting live model output.
3. Run npm run verify to cover typecheck, tests, replay evals, surface smoke, and build.
4. Review export and handoff artifacts as operator-facing proof, not just the chat flow.

System Overview

Evaluation Path

• Start here: Open the Cloudflare demo, run one incident scenario, then inspect replay eval coverage.
• Local demo: Run npm install && npm run dev; the UI runs on http://127.0.0.1:3000 and API on http://127.0.0.1:8787.
• Checks: Run npm run verify; it covers typecheck, tests, replay evals, surface smoke, and build.

Architecture Notes

• Architecture guide summarizes the system scope, first files to inspect, runtime commands, and known boundaries.
• Quality notes lists the local checks, CI surface, and release expectations for this repository.
• Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

Live Demo

---

Architecture

flowchart LR
    subgraph Intake ["1 - Intake"]
        Logs["Raw Logs"]
        Screenshots["Monitoring Screenshots"]
    end

    subgraph Analysis ["2 - Multimodal Analysis"]
        API["Express API\n(server-side key handling)"]
        Gemini["Gemini"]
        OpenAI["OpenAI"]
        Ollama["Ollama (local)"]
        Demo["Demo mode\n(no keys)"]
    end

    subgraph Output ["3 - Structured Output"]
        Report["Incident Report\n(JSON schema)"]
        Postmortem["Postmortem Pack\nSeverity + RCA + Timeline"]
        FollowUp["Follow-Up Q&A\n(grounded on report)"]
        TTS["Audio Briefing\n(TTS)"]
    end

    subgraph Eval ["4 - Replay Evals"]
        Suite["4 scenarios\n32 rubric checks"]
        Buckets["Failure Buckets\nby category"]
    end

    subgraph Handoff ["5 - Operator Handoff"]
        Export["JSON / Markdown\nSlack / Jira"]
        Workspace["Google Workspace\nDocs / Slides / Sheets\nCalendar / Chat"]
        Persist["GCS Artifacts\nBigQuery Analytics"]
    end

    Logs --> API
    Screenshots --> API
    API --> Gemini
    API --> OpenAI
    API --> Ollama
    API --> Demo
    Gemini --> Report
    OpenAI --> Report
    Ollama --> Report
    Demo --> Report
    Report --> Postmortem
    Report --> FollowUp
    Report --> TTS
    Report --> Suite
    Suite --> Buckets
    Report --> Export
    Report --> Workspace
    Report --> Persist

Key design principle: API keys never reach the browser. The React frontend calls /api/analyze, /api/followup, /api/tts -- the Express API reads provider keys server-side and returns validated, schema-conformant JSON.

---

Prerequisites

• Node.js >= 20 and npm
• (Optional) A Gemini or OpenAI API key for live analysis
• (Optional) Ollama for fully offline local analysis

Run locally

## 1. Clone and install
git clone https://github.com/KIM3310/AegisOps.git
cd AegisOps
npm install


## 2. Configure (optional -- runs in demo mode without keys)
cp .env.example .env

## 3. Start both API and UI
npm run dev

## API: http://127.0.0.1:8787

If no API key is set, the system runs in demo mode -- deterministic output, no external calls, and the full replay eval suite still runs.

Verify the build

npm run verify   # typecheck + test + replay evals + surface smoke + build

---

Tech Stack

---

Core API

---

Incident Replay Evals

The replay eval suite validates report quality against fixed scenarios with a structured rubric before the live model path is trusted.

npm run eval:replays

Rubric categories

Current scenarios

See docs/INCIDENT_REPLAY_EVALS.md for full documentation.

---

Local development

npm install && npm run dev

Cloudflare Pages

npm run build && wrangler pages deploy dist/

Docker / Cloud Run

docker build -t aegisops .
docker run -e GEMINI_API_KEY=<key> -e HOST=0.0.0.0 -p 8787:8787 aegisops

Terraform (GCP Cloud Run)

cd infra/terraform
terraform init
terraform plan -var="project_id=<your-project>" -var="image=<your-image>"
terraform apply

Kubernetes

Pre-built manifests in infra/k8s/ include Deployment, Service, HPA, Ingress, and ConfigMap.

Optional GCP persistence

Set GOOGLE_APPLICATION_CREDENTIALS + GCP_PROJECT_ID to persist incident artifacts to GCS and analytics rows to BigQuery.

---

Project Structure

AegisOps/
  App.tsx                    # React app root
  types.ts                   # Shared TypeScript types
  constants.ts               # Sample presets, review lenses
  components/                # React UI components (26 files)
  hooks/                     # React hooks (app state, auth, storage)
  services/                  # Frontend service clients (Google APIs, Gemini, export)
  server/
    index.ts                 # Express API server (~700 lines, 15+ routes)
    lib/
      gemini.ts              # Gemini provider (analyze, follow-up, TTS)
      openai.ts              # OpenAI provider (analyze, follow-up)
      ollama.ts              # Ollama provider (analyze, follow-up)
      demo.ts                # Deterministic demo mode
      replayEvals.ts         # Replay eval scoring and bucket aggregation
      schemas.ts             # Zod request validation schemas
      operatorAccess.ts      # Bearer + OIDC operator auth
      gcp-persistence.ts     # GCS artifact upload, BigQuery analytics
      prometheus.ts          # Prometheus metrics
      datadog-adapter.ts     # Datadog integration
      aws-adapter.ts         # AWS S3/SQS/CloudWatch integration
      ...
  evals/
    incidentReplays.ts       # 4 replay scenarios with expected rubrics
  __tests__/                 # 29 test files (Vitest)
  scripts/                   # CLI tools (replay runner, smoke tests, load tests)
  infra/
    terraform/               # GCP Cloud Run IaC
    k8s/                     # Kubernetes manifests
  docs/                      # Architecture docs, evidence, SVGs
  samples/                   # Sample logs, screenshots, resource packs
  .github/workflows/         # CI pipeline (test, build, artifact upload)

---

Testing

npm test                    # Unit tests (Vitest, 29 test files)
npm run typecheck           # TypeScript strict mode check
npm run eval:replays        # Replay eval suite (4 scenarios / 32 checks)
npm run architecture:smoke        # Review surface smoke tests
npm run verify              # All of the above + build

---

Environment Variables

See .env.example for the full list. Key variables:

---

Cloud + AI Architecture

• Cloud + AI architecture blueprint
• Machine-readable architecture manifest
• Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

• Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

System Architecture

• System architecture maps the runtime boundary, data/control flow, cloud or local deployment surface, and operating assumptions for this repository.

Service Architecture

• Service architecture defines the cloud resources, account information, usage controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.

Search And Service Surface

• Public entry: public replay demo plus downloadable incident-readout template
• Paid boundary: team workspace for incident packs, replay history, export branding, and private provider keys
• Canonical URL: https://aegisops-ai-incident-doctor.pages.dev/
• Lead capture: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=AegisOps&inquiry=incident-operations-exercise#private-inquiry
• Resource route: https://kim3310-doeon-kim-portfolio.pages.dev/resources/AegisOps/
• Commercial route: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=AegisOps#service-offers
• Machine-readable offer: docs/service-offer.json
• Search growth implementation: docs/search-growth-implementation.md
• Revenue architecture: docs/revenue-architecture.md