# tripleten-com/ai-system-engineering-showcase architecture

> Architecture diagram of the GitHub repository tripleten-com/ai-system-engineering-showcase, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tripleten-com/ai-system-engineering-showcase
- Repository: https://github.com/tripleten-com/ai-system-engineering-showcase

## Overview

TripleTen is a production-shaped incident-response showcase. An engineer triggers a deterministic incident in the War Room; the API generates telemetry and evidence, sanitizes logs, retrieves a runbook, and runs a checkpointed agent plan that pauses for human approval. Approval dispatches a validated job to a worker, which records simulated remediation, archives a postmortem, and reports completion so telemetry can recover and the UI can display the outcome. The graph preserves the documented storage and observability integrations. Source excerpts are partial, so uncertain internal call wiring is omitted.

Main entry points: [`services/remediation-worker/src/remediation_worker/consumer.py`](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/consumer.py) (Job Consumer), [`services/incident-agent-api/src/incident_agent_api/agent/graph.py`](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/graph.py) (Agent Graph), [`services/incident-war-room/src/services/api.ts`](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/services/api.ts) (API Client), [`services/incident-agent-api/src/incident_agent_api/agent/orchestrator.py`](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/orchestrator.py) (Run Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_warroom["Incident War Room"]
  node_warroom_app["War Room UI<br/>[App.tsx]"]
  node_stream_hook["Incident Stream"]
  node_sse_client["SSE Client<br/>[sseClient.ts]"]
  node_ui_api["API Client<br/>[api.ts]"]
  node_rag_view["RAG Inspector"]
end

subgraph group_api["API Control Plane"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_incident_routes["Incident Routes<br/>[incidents.py]"]
  node_stream_routes["Stream Routes<br/>[stream.py]"]
  node_retrieval_routes["Retrieval Routes<br/>[retrieval.py]"]
end

subgraph group_reasoning["Analysis and Planning"]
  node_orchestrator["Run Orchestrator<br/>[orchestrator.py]"]
  node_agent_graph["Agent Graph<br/>[graph.py]"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_sanitizer["Evidence Sanitizer<br/>[sanitizer.py]"]
  node_hybrid_search["Hybrid Search<br/>[hybrid_search.py]"]
  node_seed_ingest["Runbook Ingestion<br/>[ingest.py]"]
end

subgraph group_telemetry["Telemetry and Evidence"]
  node_telemetry_engine["Telemetry Engine<br/>[engine.py]"]
end

subgraph group_worker["Async Remediation"]
  node_worker_daemon["Worker Daemon<br/>[main.py]"]
  node_job_consumer["Job Consumer<br/>[consumer.py]"]
  node_handlers["Remediation Handlers"]
  node_postmortem["Postmortem Archive<br/>[postmortem.py]"]
  node_callback["Completion Callback<br/>[callback.py]"]
end

node_engineer(("Engineer"))
node_contracts["Shared Contracts"]
node_postgres[("PostgreSQL pgvector")]
node_redis[("Redis")]
node_sqs["SQS Queues"]
node_s3[("S3 Storage")]
node_prometheus[("Prometheus")]
node_jaeger[("Jaeger")]

node_engineer -->|"triggers / approves"| node_warroom_app
node_warroom_app -->|"requests actions"| node_ui_api
node_ui_api -->|"HTTP calls"| node_incident_routes
node_ui_api -->|"searches runbooks"| node_retrieval_routes
node_incident_routes -->|"starts / authorizes"| node_orchestrator
node_orchestrator -->|"transitions run state"| node_telemetry_engine
node_orchestrator -->|"invokes workflow"| node_agent_graph
node_agent_graph -->|"sanitizes evidence"| node_sanitizer
node_agent_graph -->|"retrieves guidance"| node_hybrid_search
node_agent_graph -->|"validates tools"| node_guardrails
node_orchestrator -->|"dispatches approved job"| node_sqs
node_agent_graph -->|"checkpoints state"| node_postgres
node_seed_ingest -->|"stores runbooks"| node_postgres
node_hybrid_search -->|"searches runbooks"| node_postgres
node_telemetry_engine -->|"publishes metrics"| node_prometheus
node_telemetry_engine -->|"publishes frames"| node_stream_routes
node_stream_routes -->|"streams events"| node_sse_client
node_stream_hook -->|"subscribes"| node_sse_client
node_stream_hook -->|"fetches snapshot"| node_ui_api
node_warroom_app -->|"renders state"| node_stream_hook
node_rag_view -->|"probes retrieval"| node_ui_api
node_worker_daemon -->|"polls queue"| node_job_consumer
node_job_consumer -->|"receives jobs"| node_sqs
node_job_consumer -->|"executes approved tools"| node_handlers
node_job_consumer -->|"checks idempotency"| node_redis
node_job_consumer -->|"records results"| node_postmortem
node_postmortem -->|"archives report"| node_s3
node_job_consumer -->|"reports completion"| node_callback
node_callback -->|"notifies API"| node_incident_routes
node_worker_daemon -->|"refreshes heartbeat"| node_redis
node_api_app -.->|"exports traces"| node_jaeger
node_contracts -->|"defines payload types"| node_warroom_app

click node_warroom_app "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/App.tsx"
click node_stream_hook "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/hooks/useIncidentStream.ts"
click node_sse_client "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/services/sseClient.ts"
click node_ui_api "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/services/api.ts"
click node_rag_view "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/components/RagInspectorView.tsx"
click node_api_app "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/main.py"
click node_incident_routes "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/api/routes/incidents.py"
click node_stream_routes "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/api/routes/stream.py"
click node_retrieval_routes "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/api/routes/retrieval.py"
click node_orchestrator "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/orchestrator.py"
click node_agent_graph "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/graph.py"
click node_guardrails "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/guardrails.py"
click node_sanitizer "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/security/sanitizer.py"
click node_hybrid_search "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/retrieval/hybrid_search.py"
click node_seed_ingest "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/seed/ingest.py"
click node_telemetry_engine "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/telemetry/engine.py"
click node_worker_daemon "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/main.py"
click node_job_consumer "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/consumer.py"
click node_handlers "https://github.com/tripleten-com/ai-system-engineering-showcase/tree/main/services/remediation-worker/src/remediation_worker/handlers"
click node_postmortem "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/postmortem.py"
click node_callback "https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/callback.py"
click node_contracts "https://github.com/tripleten-com/ai-system-engineering-showcase/tree/main/packages/contracts/src/tripleten_contracts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_warroom_app,node_stream_hook,node_sse_client,node_ui_api,node_rag_view toneBlue
class node_api_app,node_incident_routes,node_stream_routes,node_retrieval_routes,node_postgres,node_redis,node_s3,node_prometheus,node_jaeger toneAmber
class node_orchestrator,node_agent_graph,node_guardrails,node_sanitizer,node_hybrid_search,node_seed_ingest toneMint
class node_telemetry_engine,node_sqs toneRose
class node_worker_daemon,node_job_consumer,node_handlers,node_postmortem,node_callback,node_engineer toneIndigo
class node_contracts toneTeal
```

## Components

### Incident War Room

- [War Room UI](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/App.tsx): `services/incident-war-room/src/App.tsx`
- [Incident Stream](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/hooks/useIncidentStream.ts): `services/incident-war-room/src/hooks/useIncidentStream.ts`
- [SSE Client](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/services/sseClient.ts): `services/incident-war-room/src/services/sseClient.ts`
- [API Client](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/services/api.ts): `services/incident-war-room/src/services/api.ts`
- [RAG Inspector](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-war-room/src/components/RagInspectorView.tsx): `services/incident-war-room/src/components/RagInspectorView.tsx`

### API Control Plane

- [FastAPI App](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/main.py): `services/incident-agent-api/src/incident_agent_api/main.py`
- [Incident Routes](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/api/routes/incidents.py): `services/incident-agent-api/src/incident_agent_api/api/routes/incidents.py`
- [Stream Routes](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/api/routes/stream.py): `services/incident-agent-api/src/incident_agent_api/api/routes/stream.py`
- [Retrieval Routes](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/api/routes/retrieval.py): `services/incident-agent-api/src/incident_agent_api/api/routes/retrieval.py`

### Analysis and Planning

- [Run Orchestrator](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/orchestrator.py): `services/incident-agent-api/src/incident_agent_api/agent/orchestrator.py`
- [Agent Graph](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/graph.py): `services/incident-agent-api/src/incident_agent_api/agent/graph.py`
- [Guardrails](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/agent/guardrails.py): `services/incident-agent-api/src/incident_agent_api/agent/guardrails.py`
- [Evidence Sanitizer](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/security/sanitizer.py): `services/incident-agent-api/src/incident_agent_api/security/sanitizer.py`
- [Hybrid Search](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/retrieval/hybrid_search.py): `services/incident-agent-api/src/incident_agent_api/retrieval/hybrid_search.py`
- [Runbook Ingestion](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/seed/ingest.py): `services/incident-agent-api/src/incident_agent_api/seed/ingest.py`

### Telemetry and Evidence

- [Telemetry Engine](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/incident-agent-api/src/incident_agent_api/telemetry/engine.py): `services/incident-agent-api/src/incident_agent_api/telemetry/engine.py`

### Async Remediation

- [Worker Daemon](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/main.py): `services/remediation-worker/src/remediation_worker/main.py`
- [Job Consumer](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/consumer.py): `services/remediation-worker/src/remediation_worker/consumer.py`
- [Remediation Handlers](https://github.com/tripleten-com/ai-system-engineering-showcase/tree/main/services/remediation-worker/src/remediation_worker/handlers): `services/remediation-worker/src/remediation_worker/handlers`
- [Postmortem Archive](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/postmortem.py): `services/remediation-worker/src/remediation_worker/postmortem.py`
- [Completion Callback](https://github.com/tripleten-com/ai-system-engineering-showcase/blob/main/services/remediation-worker/src/remediation_worker/callback.py): `services/remediation-worker/src/remediation_worker/callback.py`

### Other components

- **Engineer**
- [Shared Contracts](https://github.com/tripleten-com/ai-system-engineering-showcase/tree/main/packages/contracts/src/tripleten_contracts): `packages/contracts/src/tripleten_contracts`
- **PostgreSQL pgvector**
- **Redis**
- **SQS Queues**
- **S3 Storage**
- **Prometheus**
- **Jaeger**

## Connections

- Engineer → War Room UI: triggers / approves
- War Room UI → API Client: requests actions
- API Client → Incident Routes: HTTP calls
- API Client → Retrieval Routes: searches runbooks
- Incident Routes → Run Orchestrator: starts / authorizes
- Run Orchestrator → Telemetry Engine: transitions run state
- Run Orchestrator → Agent Graph: invokes workflow
- Agent Graph → Evidence Sanitizer: sanitizes evidence
- Agent Graph → Hybrid Search: retrieves guidance
- Agent Graph → Guardrails: validates tools
- Run Orchestrator → SQS Queues: dispatches approved job
- Agent Graph → PostgreSQL pgvector: checkpoints state
- Runbook Ingestion → PostgreSQL pgvector: stores runbooks
- Hybrid Search → PostgreSQL pgvector: searches runbooks
- Telemetry Engine → Prometheus: publishes metrics
- Telemetry Engine → Stream Routes: publishes frames
- Stream Routes → SSE Client: streams events
- Incident Stream → SSE Client: subscribes
- Incident Stream → API Client: fetches snapshot
- War Room UI → Incident Stream: renders state
- RAG Inspector → API Client: probes retrieval
- Worker Daemon → Job Consumer: polls queue
- Job Consumer → SQS Queues: receives jobs
- Job Consumer → Remediation Handlers: executes approved tools
- Job Consumer → Redis: checks idempotency
- Job Consumer → Postmortem Archive: records results
- Postmortem Archive → S3 Storage: archives report
- Job Consumer → Completion Callback: reports completion
- Completion Callback → Incident Routes: notifies API
- Worker Daemon → Redis: refreshes heartbeat
- FastAPI App → Jaeger: exports traces
- Shared Contracts → War Room UI: defines payload types